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WinSock network socket driver subsystem and method for windows emulator running under 
unix operating system 



(57) A computer system comprising at least one ap- 
plications program, a Unix operating system API, and a 
WinSock socket driver. The applications program per- 
forms predetermined processing operations : and issues 
Windows operating system calfs, including WinSock 
socket calls. The Unix operating system API provides, 
in response to Unix socket calls, Unix socket services 
in connection with at least one socket connection to an- 
other computer system over a network. The WinSock 
socket driver receives WinSock socket calls from said 
applications program and emulates the WinSock socket 
calls in connection with Unix socket calls to said Unix 
operating system API. In emulating at least some of the 
WinSock socket calls, the WinSock socket driver makes 
use of Unix socket calls at least some of which block, 
but effectively controls the computer system to execute 
such calls in a non-blocking manner. 
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Description 

The present invention relates generally to the field of digital computer systems and more specifically to arrange- 
ments for controlling communications among digital computer systems which may commun.cate over, for example, a 

"Uniarticular the present invention provides a WinSock network socket driver system and method for use in con- 
nection with a Windows emulator running under the Unix operating system program, to provide WinSock socket serv,ces 
to Windows applications programs. 

The following references are incorporated herein by reference:- 

a) "Windows Sockets: An Open Interface For Network Programming Under Microsoft® Windows™" Version 1.1. 
20 January 1 993. (hereinafter referred to as "the WinSock specification") attached hereto as a Appendix *and 

b) "The X Toolkit Intrinsics Reference Manual" (O'Reilly & Associates: 1990), copyright page and pages 86-88, 
301 and 304 attached hereto as Appendix B. 

In modern "enterprise" computing, personal computers and workstations distributed among workers in the enter- 
prise are replacing the previously-used large and expensive, centrally-located and mainta.ned ™n*™^^ r 
systems. One advantage that mainframe systems have over more modern distributed arrangements, howeveus that 
since they are centrally-located, they more easily provide for sharing of data and programs, wh.ch can be mportan. :n 
20 an enterprise environment. To facilitate program and data sharing among persona, computers ane [^^%2ms 
works have been developed over which one personal computer or workstation can make use of data and Programs 
I another "remote" device, in general by causing the data and programs to be "downloaded," that ,s, transferred to 

K f °Tn 0 uTbeTof network communication paradigms have been developed to help facilitate communications over a 
25 network including, for example, virtual circuits, "sockets" or the like. Using such paradigms, an applications program 
exlcuting on one computer system may transmit data to, or receive data from, another computer ay. am over the 
network merely by referencing" an underlying virtua. circuit or socket. The network operating system w, ™J™ 
data and perform the actual transfer. Indeed, the applications program may not even need to be aware that the data 
is being transferred to, or received from, another computer system. notu/rtfk 
A number of operating system programs may be used in the various computer systems connected to a network 
including the well-known Unix operating system program and the Microsoft Windows operating system program _The 
socket network transfer paradigm was developed by the University of California at Berkeley, and have been P^nze6 
in its Berkeley Software Distribution ("BSD"). The BSD Unix Sockets paradigm defines a number o function calls wh.ch 
allow an apoLtions program to control and access a number of network events. A sim.lar socket parad ,gm has been 
3S developed for Windows, identified as "WinSock", which includes the Unix socket calls and a number of addrt.onal calls 
(Windows "extensions") provided to allow applications programs to have message-based, asynchronous access to a 
variety of network events. A number of the BSD Unix socket cal.s are "blocking," that is. when an ™!™ a 
issues a socket call, the applications program does not receive the results until the operation. W**"^^"? 
been completed. A number of the socket calls may take an arbitrary period of time to complete. In connection with 
40 Windows, however, it is preferable that the WinSock calls be performed in a non-blocking manner. 

SUMMARY OF THE INVENTION 

The invention provides a new and improved WinSock network socket driver system and ^««hc^or use incon- 
45 nection with a Windows emulator operating under the Unix operating system program, to provide WinSock socket 
services for Windows applications programs operating under the Windows emulator. 

,n brief summary, in one aspect the invention provides a computer system comprising at least one applications 
program, a Unix operating system API, and a WinSock socket driver. The applications program performs Pjedete^ed 
-rccessinq operations and issues Windows operating system calls, including WinSock socket calls. The Unix operating 
so £ Z API providing in response to Unix socket ca.ls, Unix socket services in connection with at .east one mkx** 
connection to another computer system over a network. The WinSock socket dnver recede , WmSock socket calls 
from said applications program and emulates the WinSock socket calls in connect.on with Unix socket calls to sa.d 

UniX ,n anoter afpecT fhe invention provides a non-pre-emptive mu.ti-tasking emulator, for use in connection with a 
ss computer, for emufcting a blockable call issued by an applications program. The blockab.e ca.l has a duration parameter 
whTch specifies a duraL over which a specified operation to be performed. The blockab.e call block* other opart ons 
Tor the duration whi.e the b.ockable ca.l is being executed. The emulator emulates the b.ockab.e call ,n a norv -btetong 
manner The emulator comprises a timer, a blockable call issuer and a non-blockable iteration control element. The 
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timer enables generation ofa timing indication at the end of a timing interval corresponding to the duration specified 
by the duration parameter. The blockable call issuer issues the blockable call with a duration parameter specifying an 
instantaneous duration thereby enabling the specified operation to be performed instantaneously. Finally the non- 
blockable iteration control element in a series of iterations, enables the blockable call issuer to issue the blockable 
call until the timer generates the timing indication. The non-blockable control element is non-pre-emptively interruptible 
during each iteration, at least while the blockable call is not being executed, thereby to provide for the non-blocking 
emulation of the otherwise blockable call. 

The present invention will now be further described, by way of example : with reference to the accompanying 
drawings, in which: - 

FIG. 1 depicts an illustrative computer system incorporating a network socket driver arrangement in accordance 
with the invention: 

FIG. 2 schematically represents a functional block diagram of the network socket driver in relation to other functional 
elements of the computer system depicted in FIG. 1 : and 

FIGs. 3 and 4 depict flow diagrams illustrating operations performed by the network socket driver which are useful 
in understanding the invention. 

DETAILED DESCRIPTION OF AN ILLUSTRATIVE EMBODIMENT 

FIG. 1 depicts an illustrative computer system 10 constructed in accordance with the invention. With reference to 
FIG. 1 : the computer system 10 in one embodiment includes a processor module 11 and operator interface elements 
comprising operator input components such as a keyboard 1 2 A and/or a mouse 1 2B (generally identified as operator 
input element(s) 12) and an operator output element such as a video display device 13. The illustrative computer 
system 10 is of the conventional stored-program computer architecture. The processor module 11 includes, for exam- 
ple, processor, memory and mass storage devices such as disk and/or tape storage elements (not separately shown) 
which perform processing and storage operations in connection with digital data provided thereto. The operator input 
element(s) 12 are provided to permit an operator to input information for processing. The video display device 13 is 
provided to display output information generated by the processor module 11 on a screen 14 to the operator, including 
data that the operator may input for processing, information that the operator may input to control processing, as well 
as information generated during processing. The processor module 11 generates information for display by the video 
display device 13 using a so-called "graphical user interface" ("GUI"), in which information for various applications 
programs is displayed using various "windows." Although the computer system 10 is shown as comprising particular 
components, such as the keyboard 12A and mouse 12B for receiving input information from an operator, and a video 
display device 13 for displaying output information to the operator, it will be appreciated that the computer system 10 
may include a variety of components in addition to or instead of those depicted in FIG. 1 . 

In addition, the processor module 1 1 includes one or more network ports, generally identified by reference numeral 
14, which are connected to communication links which connect the computer system 10 in a computer network. The 
network ports enable the computer system 10 to transmit information to, and receive information from, other computer 
systems and other devices in the network. In a typical network organized according to, for example, the client-server 
paradigm, certain computer systems in the network are designated as servers, which store data and programs (gen- 
erally, "information") for processing by the other, client computer systems, thereby to enable the client computer systems 
to conveniently share the information. A client computer system which needs access to information maintained by a 
particular server will enable the server to download the information to it over the network. After processing the data, 
the client computer system may also return the processed data to the server for storage. In addition to computer 
systems (including the above-described servers and clients), a network may also include, for example, printers and 
facsimile devices, digital audio or video storage and distribution devices, and the like, which may be shared among 
the various computer systems connected in the network. The communication links interconnecting the computer sys- 
tems in the network may, as is conventional, comprise any convenient information-carrying medium, including wires, 
optical fibers or other media for carrying signals among the computer systems. Computer systems transfer information 
over the network by means of messages transferred over the communication links, with each message including in- 
formation and an identifier identifying the device to receive the message. 

FIG. 2 depicts a functional block diagram of functional elements of the computer system 10 depicted in FIG. 1 
useful in understanding the invention. With reference to FIG. 2, an applications programs 21 will initiate and engage 
in a communications session over the network by making appropriate calls through a Windows emulator 1 7, in particular 
to the Windows socket driver constructed in accordance with the invention. The applications programs 21 are conven- 
tional applications programs which run under the Microsoft Windows operating system program ("Windows™"), and 
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the computer system 10 itself, instead of running Windows, runs the well-known Unix operating system program. In 
one embodiment, the computer system 10 runs Unix with XWindows extensions (hereinafter "Unix/XWindows"). The 
Windows emulator 17 also provides a Windows applications programming interface ("API") which receives Windows 
operating system calls from the Windows applications programs 21. processes them and generates Umx/XWindows 
s operating system program calls as appropriate, which it provides to the Unix/XWindows operating system program 
through its API 20. The Windows emulator 17 further receives appropriate responses from the Unix/XWindows oper- 
ating system program through the API 20, which it may process for use by the Windows applications program 21. 

The Unix operating system program provides a number of operating system services to the Windows emulator, 
as well as to Unix applications programs (not shown in FIG. 2) which may be processed by the computer system 10, 

10 including those described in. for example, Kernighan and Pike, "The Unix Programming Environment", (Prentice-Hall. 
1984), and the XWindows extensions are described in a number of publications, including "The X Toolkit Intnnsics 
Reference Manual" (O'Reilly & Associates: 1990). Illustrative services provided by the operating system program in- 
clude, for example, receiving operator input from an operator input device, such as keyboard 12A or mouse 12B, for 
provision to the applications program 21 , receiving information from the applications program for display to the operator 

'5 and displaying it on the display device 13 in one or more windows, and retrieving data from stored on the computer 
system's storage devices for processing by the applications program and storing processed data thereon. In addition, 
the operating system program receives network communication session calls from an applications program 21 and 
provides them to a network path 22, which to handles communications with another computer system (not shown) 
during the session, and provides responses from the network path 22, which may include data to be processed, to the 

20 applications program 21. 

The network path 22 includes a Unix network socket driver 23, a TCP/IP stack module 24 and the network port 
14. In one embodiment, the network socket driver 23 provides network services in the form of a "socket," which is a 
well-known paradigm for facilitating communications between pairs of computer systems in a network (see, for example, 
A. Tanenbaum, Computer Networks , 2d Ed. (Prentice-Hall, 1988), pp. 434-435). A socket facilitates communications 

2S over a network between two computer systems which are connected to the network, including handling addressing, 
message buffering, message flow control, and so forth, to facilitate transfer of messages between pairs of computer 
systems for particular programs being processed by those computer systems, and provides a uniform mterface to 
which TCP/IP stack modules from various manufacturers can interface. When one applications program 21 has infor- 
mation to be transferred to another applications program on another "remote" computer system, a socket arrangement 

30 will ensure that the transferring computer system will provide a message for the information which identifies the com- 
puter system as the intended recipient, and further that the message will identify the other applications program as the 
intended recipient of the information contained in the message. 

The TCP/IP stack module 24 provides conventional TCP/IP services in connection with information provided there- 
to by the network socket driver 23 to be transmitted by the network port 14, and also in connection with messages 

3S received by the network port 1 4. The network port 1 4 transmits messages over the network communication links gen- 
erally identified by reference numeral 31 . and also receives messages from the network communication links 31 which 
were transmitted by other devices connected in the network. The network port 14 will determine from the addresses 
in the message whether the intended recipient for the message is the computer system 10, and if so it will pass the 
message to the TCP/IP stack module 24 for further handling. 

■to The WinSock socket driver 1 9 provides emulation services conforming to the specification entitled "Windows Sock- 

ets- An Open Interface For Network Programming Under Microsoft Windows™," (hereinafter "the WinSock specifica- 
tion") which specifies the application programming interface ("API") for socket drivers for use in connection with Mi- 
crosoft Windows™ operating system and applications programs operating thereunder. (The WinSock specification is 
attached hereto as a Appendix A and incorporated herein by reference.) 

45 The WinSock specification defines an API which includes a number of calls based on a Unix sockets API which 

has been popularized in the Berkeley Software Distribution ("BSD") developed by the University of California at Berkeley 
(hereinafter "basic socket calls"), with a number of additional calls (Windows "extensions") provided to allow applica- 
tions programs to have message-based, asynchronous access to a variety of network events. Services performed by 
the WinSock socket driver 1 9 in connection with WinSock calls include, for example, starting a socket connection to 

so another computer system over the network, accepting a socket connection started from another computer system over 
the network, receiving data from an applications program 21 for transmission over the socket connection (corresponding 
to a "write" to the socket connection), receiving data from a socket connection for transfer to an applications program 
(corresponding to a "read" from the socket connection), selecting a socket to check its status, and closing a socket 
connection It will be appreciated that the WinSock socket driver 1 9, in emulating at least some of the WinSock socket 

55 calls from a Windows applications program 21 . will make calls through the Unix/XWindows operating system program 
API 20 which in turn, depending on the call, may also enable the network path 22 to perform selected operations. 

In accordance with the invention the WinSock socket driver 19 provides a WinSock API for Windows applications 
programs 21 which operate under the Unix operating system program with Xwindows extensions. Since the Unix op- 
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erating system program performs multi-tasking in a pre-emptive manner, blocking in connection with a call by an ap- 
plications program operating under the Unix operating system program, or Unix with XWindows extensions, does not 
interfere with operations in connection with other applications programs which may be executed contemporaneously 
with the calling applications program in a multi-tasked manner. The WinSock socket driver 19 provides emulation 
s services in connection with the basic socket calls (that is, the calls corresponding to the socket calls as defined by 
BSD's Unix sockets API). A number of the basic socket calls defined by the BSD Unix sockets API are "blocking.- that 
is. when an applications program issues a socket call, a value is not returned to the applications program 21 until the 
operation requested in the call has been completed. A number of the socket calls may take an arbitrary period of time 
to complete. The WinSock socket driver 19 emulates the socket calls corresponding to the basic socket calls defined 
io by BSD's Unix sockets API, although it performs them in a non-blocking manner. Since Windows performs multi-tasking 
in a non-pre-emptive manner, blocking in connection with a call by an applications program operating under Windows 
can interfere with operations in connection with other applications programs which may be executed contemporane- 
ously with the calling applications programs. 

In addition, the WinSock socket driver 19 provides emulation services in connection with the Windows extension 
operations as defined by the WinSock specification, including a number of operations which are performed which are 
analogous to the operations which are performed in response to a BSD Unix socket API call which may block, but 
which will perform the operations in a non-blocking manner. When the WinSock socket driver 19 initiates processing 
of a Windows extension operation in response to a call from an applications program 21 , it (the WinSock socket driver 
1 9) initially provides an acknowledgment value which operates as an asynchronous task handle, or an identifier, which 
identifies the operation. After receiving the call acknowledgment from the WinSock socket driver 19, the applications 
program 21 may be able to continue performing its processing operations. When the WinSock socket driver 1 9 finishes 
the operation, it provides a notification to the applications program 21 that the operation has completed, along with the 
information, if any, as requested by the call, or an error indication indicating that an error has occurred in processinq 
the request. 

The operations performed by the WinSock socket driver 1 9 will be illustrated in connection with two WinSock calls 
which will be described in detail in connection with FIGs. 3 through 3 (CONT. C) and FIGs. 4 through 4 (CONT. C). 
Both of the calls provide information to a calling applications program as to the status of a socket connection. Generally 
for WinSock calls which correspond to the Unix basic socket calls, the Unix/XWindows operating system API 20 is able 
to perform operations corresponding to those provided by the WinSock calls, although perhaps in a manner which may 
block, using the Unix/XWindows 1 call processing elements, and in that case the WinSock socket driver 19 . will (a) 
generate parameters for the Unix basic socket call from parameters provided in the WinSock call and, if necessary, 
other information available to it and (b) issue the Unix basic socket call with the parameters so generated to the Unix) 
XWindows operating system API 20 in a non -blocking manner, perhaps in a series of iterations until a required response 
is provided by the Unix/XWindows operating system API 20 or the call is cancelled by, for example, the calling appli- 
cations program 21 , On the other hand, for WinSock calls which do not correspond to the Unix basic socket calls, the 
WinSock socket driver 19 will process the calls preferably without making use of Unix basic socket calls which may 
block, although it may make use of non-blocking Unix/XWindows calls. 

- These will be illustrated in connection with two specific WinSock calls, namely (1 ) the WinSock Synchronous Select 
call, which is a Winsock call that corresponds to a Unix basic socket call, and (2) the WinSock Asynchronous Select, 
which is a WinSock Windows Extension call, both of which will provide information to a calling applications program 
21 as to the current status of a socket connection or monitor the socket connection over a period of time for the oc- 
currence of selected events. As will be clear from the following, the WinSock socket driver 1 9, in executing the WinSock 
Synchronous Select call, makes use of the Unix Synchronous Select call, which under some circumstances may block, 
but the driver 19 uses the Unix Synchronous Select call in a "polling" manner to ensure that it does not block. In 
executing a WinSock Synchronous Select call which enables monitoring over a selected period of time, the WinSock 
socket driver 19 will make use of a non-blocking Xwindows extension call, namely, an XtAppAddTimeOut() call to the 
Unix/XWindows operating system API 20.. which is described in The X Toolkit Intrinsics Reference Manual" (OReilly 
& Associates: 1 990), page 88, in Appendix B attached hereto. In response to the XtAppAddTimeOut() call, the Unix/ 
XWindows operating system API 20 will notify the WinSock socket driver 19 at the end ofa selected time interval, 
identified in the call, following issuance of the call, which the Winsock socket driver may use to determine when the 
time period over which monitoring is to occur is to end. 

On the other hand, in executing the WinSock Asynchronous Select Call, the WinSock socket driver 19 will not 
make use of a Unix basic socket call, but will make use of a non-blocking XWindows extension call, described below 
as an XtAppAddlnput() call to the Unix/XWindows operating system API 20, which is described in "The X Toolkit In- 
trinsics Reference Manual" (O'Reilly & Associates: 1990), pages 86-87, in Appendix B attached hereto. In response 
to the XtAppAddlnputQ call, the Unix/XWindows operating system API 20 notifies the WinSock socket driver 1 9 of the 
occurrence of a particular event in connection with the computer system 10 as specified in a parameter in the XtAp- 
pAddlnput(), in this case an event related to the socket connection to be monitored. 
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1. WinSock Synchronous Select: Select (rd-sock-ptr, wrt-sock-ptr, exc-sock-ptr, tm-out) 

in response to a WinSock Synchronous Select call from an applications program 21 /the WinSock ^^river 
19 will monitor one or more sockets to determine when particular t yP e(s) of event(s) have occurr f / he J"'"^* 

5 Synchronous Se.ect cal. inc.udes a number of parameters and provides responses ^"J^^™^^ 
Synchronous Select call used in connection with the Berkeley Unix sockets as described above. In particula he 
WinSock Synchronous Select call includes parameters including a "rd-sock-ptr" ("read socket pointer ) Paramete r a 
L-sock-ptr" ("write socket pointer") parameter, an "exc-sock-ptr" ("exception socket P^^^iSfiS 
out ("time-out") parameter. The "rd-sock-ptr" (read socket pointer) parameter composes a pointer to a , tebta , wheh 

w contains identifiers) of one or more socket(s) which the WinSock socket driver 19 is to dete «ni«e « « -*We- ^ 
is. that it has data to be provided to the applications program. Similarly, the "wrt-sock-ptr" (^^Sk12cE 
rameter comprises a pointer to a table which contains identifier(s) of one or more socket(s) wh .c \*^™^ k ™ k « 
driver 19 is to verify for writeability, that is, that the socket connection has been estabhshed and can accept date or 
Transmission. The "exc-sock-ptr" (exception socket pointer) parameter comprises a pointer «°^^ e ^£ 

rs identifier(s) of one or more sockets which the WinSock socket driver 19 is to be checkec for errors >« 

conditions such as unexpected or "out-of-band" data. It will be appreciated that any of the "rd-sock-ptr ( read socket 
pointer"), the "wrt-sock-p"" ("write socket pointer") parameter, or the "exc-sock-ptr" ^'^^^^X 
rameter may comprise a null value, in which case the WinSock socket driver 19 ,s not to P erfo ^ dab '' ty - 
writeability or error/exception checking operation, respectively for any socket. The "tmouf ("time-out ) 9^°%*"*. 

20 ifies the maximum amount of time the WinSock socket driver 1 9 will perform monitoring ^^Z^Z^S^ 
the identified sockets prior to providing a response. If a null value is provided for the "tm-out pa amet ^ he W ^ock 
socket driver 19 may wait indefinitely until an event occurs in connection with one of the : .de mt.f.ed 
other hand, if a zero value is provided for the "tm-out" timeout parameter, the WinSock socket drrver 1 9 will provide^ an 
Immediate response, in which case the applications program 21 will essentially be using the synchronous Select call 

25 to poll the status of the socket(s) identified in the table(s) pointed to by the other parameters. 

With this background, operations performed by the WinSock socket driver 19 in connection with a WinSock Syn 
chronous Se.ect ca.l will be described in connection with FIGs. 3 through 3 (CONT. C). With reference to 
receiving the WinSock Synchronous Select call, the WinSock socket driver 1 9 in.tial.y obtains the con text o, _task -den 
tifier of the current task, that is, the applications program 21 , from the operating system program (step 1 00> Thereafter 

30 the WinSock socket driver 19 performs a number of operations to verify that is permitted to perfo rm the , opera ons 
' required by the WinSock Synchronous Select call. Initially, the WinSock socket driver 19 w.lh det erm 

socket structure has been initialized for the task identified by the task identifier by way of a Socket Start can (step , 1 oi ) 
and if not, will return an error value (step 1 02). If the WinSock socket driver 1 9 makes a ^^T^^^ 
101 it will sequence to step 103 to determine whether there is an outstanding block.ng operat.on associated with the 

ss applications program 21 (step 103), that is, an operation which must be completed before ^\^T^oZll 
performed. If the WinSock socket driver 1 9 makes a positive determination in step 103. rt also will return an error value 

(SteP Re?urning to step 103, if the WinSock socket driver 19 makes a negative determination in that step (that is if it 
determines that there is no outstanding b.ocking operation for applications program 21), it will ^J™***™ 
in that step, the WinSock socket driver 1 9 accesses the socket identifier table(s) which are .dent fied by theri^k 
ptr" read socket pointer, "wrt-sock-ptr" write socket pointer and "exc-sock-ptr" exception socket pointer pa arn s 
and uses the socket identifiers in the table(s) to obtain the Unix file descriptor information therefor. In 
the WinSock socket driver 1 9 will determine whether an error is encountered in connection with the ^ket .dent .hers 
or generation of the Unix file descriptor information (step 1 06), and, if so, it will return an «^^^!S^Z 
program 21 (step 107). An error may occur if, for example, the socket identifier values are outside of a selected range 
or if the callinq applications program 21 does not have the right to access the socket. 

in the other hand, if the WinSock socket driver 19 determines in step 106 that no error was encountered, . t w, 
sequence to step 108 to determine the timeout duration, ifany, as called for by the "tm-out" ^ 
in the WinSock Synchronous Select call. As noted above, the "tm-out" timeout durat.on parameter may have (.) a va ue 
of zero, in which case the WinSock Synchronous Select call has a duration of zero and the call is effective y a poll of 
the sockets identified in the tables, or (ii) a non-zero value, in which case the call has a durat.on specrf.ed n the caH 
or alternatively (hi) a value of "null," in which case the WinSock socket driver 1 9 will cont.nue mon.tonng until an .event 
occurs or the cal. is cancelled. In step 108, the WinSock socket driver 19 will initially determ.ne whether the ^ tm-out 
timeout duration parameter specified a null value. If not, the WinSock socket dnver 19 w.l. de erm.ne whethe the 
timeout value was zero (step 109). If the WinSock socket driver 19 makes a negative J**™^^^^^ 
is if the "tm-out" timeout duration parameter specified neither a null value nor a zero value), ^ W.nSock socket driver 
1 9 will issue an XtAppAddTimeOutQ XWindows call to the Unix/XWindows operating system API : 20. provid ^9 * e J"> 
out timeout duration parameter to the call, and will set a timer task flag (step 110). In response to the XtAppAddTimeOut 
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{) XWindows call, the timer task flag will be reset after a selected time period. It will be appreciated that the timer task 
flag may also be reset if the Winsock socket driver 19 issues an XtRemoveTimeOutf) XWindows call through the Unix/ 
XWindows operating system API 20. 

After issuing the XtAppAddTimeOut() call the WinSock socket driver 19 will use the Unix sockets' Unix Synchro- 
nous Select call to determine when a socket identified in the table pointed to by the "rd-sock-ptr" read socket pointer 
provided in the WinSock Synchronous Select call becomes readable : a socket identified in the table pointed to by the 
"wrt-sock-ptr u write socket pointer provided in the WinSock Synchronous Select call becomes writeable, or an exception 
occurs in a socket identified in the table pointed to by the "exc-sock-ptr 0 exception socket pointer provided in the 
WinSock Synchronous Select call. To provide that the Unix Synchronous Select call does not block, the WinSock socket 
driver 19 will issue the Unix Synchronous Select with the "tm-out" timeout parameter set to zero (step 111). In that 
case, the Unix Synchronous Select call will return immediately with a value identifying the total number of sockets : if 
any, which (i) are identified in the table pointed to by the "rd-sock-ptr" read socket pointer provided in the WinSock 
Synchronous Select call and are readable, or (ii) are identified in the table pointed to by the "wrt-sock-ptr" write socket 
pointer provided in the WinSock Synchronous Select call and are writeable, or (iii) for which an exception occurs in 
and are identified in the table pointed to by the "exc-sock-ptr w exception socket pointer provided in the WinSock Syn- 
chronous Select call. 

After returning from the Unix Synchronous Select call the WinSock socket driver 19 will again test the "tm-out" 
timeout duration parameter provided in the WinSock Synchronous Select call to determine whether it was non-zero 
(step 112) to verify that the WinSock Synchronous Select operation is not a polling operation. If the WinSock socket 
driver 19 makes a positive determination in step 112 (that is/the WinSock synchronous Select operation is not a poll), 
it then determines whether the value provided in response to the Unix Synchronous Select call provided a non-zero 
response value (step 113). If the WinSock socket driver 19 makes a negative determination in step 113 (that is, if the 
Unix Synchronous Select call provided a zero value), it will call a "blocking hook" function, which ensures that the 
WinSock Synchronous Select call will not block, allowing other applications the opportunity to run, and will determine 
whether (i) the applications program 21 has terminated the WinSock Synchronous Select operation or (ii) the timer 
task flag has been cleared by the timing out of the XtAppAddTimeOutf) call (step 1 1 4). Ifthe WinSock socket driver 1 9 
makes a negative determination in step 114, it will return to step 111 to return to the Unix Synchronous Select call. On 
the other hand, if the WinSock socket driver 19 makes a positive determination in step 1 14 (that is, if it determines 
that the calling applications program 21 has terminated the WinSock Synchronous Select operation or that the timer 
task flag has been cleared), it will terminate operations and return to the calling applications program 21 (step 115). 

The WinSock socket driver 19 will repeat the operations described above in connection with steps 111 through 
1 1 4 through a series of iterations, until it determines in step 1 1 4 that the calling applications program 21 has terminated 
the WinSock Synchronous Select operation or that the timer task flag has been cleared (as described above), or until 
it determines in step 112 that the Unix synchronous Select call. has returned a non-zero value. If the WinSock socket 
driver 1 9 determines in step 1 1 2 that the Unix Synchronous Select call has returned a non-zero value, it will sequence 
to a series of steps to generate a WinSock Synchronous Select response to the applications program's WinSock Syn- 
chronous Select call. Initially, the WinSock socket driver 1 9 will issue an XtRemoveTimeOut() call to the Unix/XWindows 
operating system API 20 to cancel the XtAppAddTimeOut call (step 116) and clear the timer task flag (step 117). 
Thereafter, the WinSock socket driver 19 will identify the particular socket(s) determined to be readable, writable or 
for which an exception was detected (step 118), and in that operation, will convert the socket identifiers from the Unix 
file descriptor identifiers to socket identifiers. The WinSock socket driver 19 will then return to the calling applications 
program 21, providing a value corresponding to the number of sockets identified in step 116 along with the socket 
identifiers themselves (step 119). 

Returning to step 109, if the WinSock socket driver 19 determines in that step that the WinSock Synchronous 
Select call's "tm-out* timeout duration parameter was zero, indicating that the Synchronous Select is a poll, it will skip 
step 110 and sequence directly to step 111 to issue a Unix Synchronous Select call in the same manner as described 
above, namely, with the timeout parameter set to zero. As described above, the Unix Synchronous Select call will return 
a value identifying the total number of sockets, if any, which (i) are identified in the table pointed to by the Vd-sock-ptr" 
read socket pointer provided in the WinSock Synchronous Select call and are readable, or (ii) are identified in the table 
pointed to by the "wrt-sock-ptr* write socket pointer provided in the WinSock Synchronous Select call and are writeable, 
or (iii) for which an exception occurs in and are identified in the table pointed to by the "exc-sock-ptr" exception socket 
pointer provided in the WinSock Synchronous Select call. Following the return from the Unix Synchronous Select call, 
the WinSock socket driver 19 will determine in step 112 that the "tm-ouf timeout duration parameter of the WinSock 
Synchronous Select call was zero, in which case it will skip steps 113 through 117 and sequence directly to step 117 
to clear the timer task flag and identify the particular soeket(s) determined to be readable, writable or for which an - 
exception was detected (step 118). The WinSock socket driver 19 will then return to the calling applications program 
21, providing a value corresponding to the number of sockets identified in step 111 along with the socket identifiers 
themselves (step 119). 
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2. Asynchronous Select: "Async Select (sock-id, win-handle, msg, ev-id)" 

In response to a WinSock Asynchronous Select call from an applications program 21 , the WinSock socket driver 
1 9, after providing the call acknowledgment to the applications program 21 . will monitor the socket identified by a "sock- 

5 id" ("socket identifier") parameter to determine when a particular type of network event, which is identified by parameter 
"ev-id" ("event identifier") has occurred. A number of diverse types of network events can be monitored as identified 
by the "ev-id" event identifier parameter, including a read-readiness event, a write-readiness event, an "out-of-band" 
data arrival event, an incoming network connection acceptance event, a completed network connection event and a 
connection close event. The WinSock Asynchronous Select call will provide a positive response in connection with 

10 monitoring of the various events if: 

(t) in connection with monitoring of a read-readiness event if the socket identified by the "sock-id" (socket identifier) 
parameter has data to be transferred to the calling applications program 21: 

is (jj) in connection with monitoring of a write-readiness event, if the socket identified by the "sock-id" (socket identifier) 

parameter can receive data from the calling applications program 21 for transmission over the network port 14: 

(iii) in connection with monitoring of an out-of-band" data arrival event, if the socket identified by the "sock-id" 
(socket identifier) parameter has received "out-of-band," or unexpected, data to be transferred to the calling ap- 

20 plications program 21 : 

(iv) in connection with monitoring of an incoming network connection acceptance event, if the socket identified by 
the "sock-id" (socket identifier) parameter has been set up in response to a socket connection establishment re- 
quest received from another device connected to the network: 

25 

(v) in connection with monitoring of a completed network connection event, if the socket identified by the "sock- 
id" (socket identifier) parameter has been set up in response to a socket connection establishment request from 
an applications program 21: and . 

30 (vi) in connection with monitoring of close-connection event, if the socket identified by the "sock-id" (socket iden- 

tifier) parameter has been closed. 

(While monitoring of the above-identified network events is specified in the WinSock Specification as attached hereto, 
it will be appreciated that the WinSock socket driver 19 may additionally or instead monitor a variety of other types of 
35 network events in connection with a WinSock Asynchronous Select call.) 

When the Winsock socket driver 1 9 determines that an event of the type "ev-id" has occurred, it provides a mes- 
sage, which corresponds to the "msg" ("message") parameter of the call, to a window identified by the "win-handle" 
("window handle") parameter. The window identified by the "win-handle" parameter will, in turn, normally be associated 
with the applications program 21 which issued the WinSock asynchronous Select call, in which case the provision of 
-to the message to the window identified by the "win-handle" parameter the WinSock socket driver 19 constitutes the 
required response to the applications program 21 . If the WinSock socket driver 1 9 encounters an error while executing 
the Asynchronous Select call, it will return an error value instead of the message parameter. The WinSock socket driver 
1 9 may encounter an error if it determines that, for example, no socket exists corresponding to the "sock-id" parameter, 
the applications program 21 does not have access privileges to the socket identified by the "sock-id" parameter, no 
-*s event corresponds to the "ev-id" parameter, and the like. 

As will be described below in detail in connection with FIGs. 4 through 4 (CONT. C), in monitoring the socket to 
determine when the required type of event has occurred, the WinSock socket driver 19 makes use various calls to the 
Unix/XWindows calls, in particular an XtAppAddlnput(), which is described in "The X Toolkit Intrinsics Reference Man- 
ual" (O'Reilly & Associates: 1 990), pages 86-87, and an XtRemovelnputQ call, which is described at page 301 of The 
so x Toolkit Intrinsics Reference Manual. (Pages 86- 88, 301 and 304 of The X Toolkit Intrinsics Reference Manual are 
attached hereto as Appendix B and incorporated herein by reference). 

The specific operations performed by the WinSock socket driver 19 in connection with the Asynchronous Select 
call will be described in detail in connection with the flow chart in FIGs. 4 through 4 (CONT. C). With reference to FIG. 
4, after receiving an Asynchronous Select call, the WinSock socket driver 1 9 initially obtains the context or task identifier 
ss of the current task, that is, the applications program 21 , from the operating system program (step 1 30). Thereafter, the 
WinSock socket driver 19 perform a number of operations to verify that it can perform the operations required by the 
Asynchronous Select call. Initially, the WinSock socket driver 19 will verify that the socket structure has been initialized 
for the task identified by the task identifier by way of a Socket Start call (step 1 31 ), and. if not, will return an error value 
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(step 132). On the other hand : if the WinSock socket driver 19 makes a positive determination in step 131 : it will 
sequence to step 133, in which it determines whether the socket identifier "sock-id* is a valid socket identifier and if 
the applications program 21 has permission to access the socket. If the WinSock socket driver 19 makes a negative 
determination in step 133. it will return an error value (step 134). Returning to step 133, if the WinSock socket driver 
1 9 makes a positive determination in that step : that is, if it determines that the applications program 21 has permission 
to access the socket it will sequence to step 135, in which it determines whether there is an outstanding blocking 
operation associated with the applications program 21 which has not been completed. If the WinSock socket driver 19 
makes a positive determination in step 135, it will return an error value (step 136). 

If the WinSock socket driver 19 makes a negative determination in step 135. it can execute the WinSock asyn- 
chronous Select call issued by the applications program 21. In thatcase : it will sequence to step 1 37 to clear a BLOCK- 
ING flag which it maintains in a socket information data structure. Clearing the BLOCKING flag will ensure that sub- 
sequent WinSock calls which are issued by the applications program 21 which may block, will not block while the 
WinSock Asynchronous Select call is being processed. Thereafter, the WinSock socket driver 19 determines whether 
the call is to implicitly re-enable notification for a network event (step 138) by one of the re-enabling functions as 
described on page 90 of the WinSock specification (Appendix A attached hereto). If the WinSock socket driver 19 
makes a positive determination in step 1 38, it adds the type of network event for which the applications program 21 is 
to be notified to a list of network events to be monitored (step 139). On the other hand, if the WinSock socket driver 
1 9 makes a negative determination in step 1 38. it will substitute the network event identified by the "ev-id" event identifier 
parameter for the monitored network event list and issue Unix/XWindows XtRemovelnput() call(s) to the Unix/XWin- 
dows operating system program to enable it to stop monitoring of network events for which monitoring was previously 
enabled (step 140). 

Following step 1 40, the WinSock socket driver 19 performs a series of steps to register for monitoring of a network 
event identified by the "ev-id" event identifier parameter using the Unix/XWindows XtAppAddlnputQ call, with the 
particular parameters of the XtAppAddlnputQ call being determined by the type of event which the Asynchronous Select 
call requested to be monitored. The Unix/XWindows XtAppAddlnputQ call provides for five parameters, including a 
context identifier, a source, a condition, a procedure identifier and client data. The context identifier identifies the context 
of the calling routine, which, in this case, corresponds to the context identifier of the applications program 21 which 
issued the Asynchronous Select call; The source parameter identifies the resource whose condition is to be monitored, 
which in this case corresponds to the socket identified by the "sock-id" socket identifier parameter obtained from the 
WinSock asynchronous Select call. The condition parameter identifies the condition which is to be monitored in re- 
sponse to the XtAppAddlnputQ call; the XtAppAddlnput() call will return when the source has the specified condition. 
The condition parameter corresponds to the ev-id event identifier parameter of the Asynchronous Select call. The 
procedure identifier identifies the procedure to be called when the condition is satisfied, and corresponds to an identifier 
which identifies the portion of the Asynchronous Select call processing routine that is to receive the return value from 
the XtAppAddlnput () routine. Finally the client data parameter identifies the data which the XtAppAddlnput() call will 
provide to the procedure identified by the procedure identifier when the condition identified by the condition identifier 
is satisfied. The client data parameter in one embodiment is a function of the socket identifier incremented by a value 
which differs among the various conditions to be monitored. 

As described above, following step 140, the WinSock socket driver 19 performs a series of steps to register for a 
callback using the XWindows XtAppAddlnput() call, with the particular parameters of the XtAppAddlnput() call being 
determined by the type of event which the Asynchronous Select call requested to be monitored. In particular the 
WinSock socket driver 19 will initially determine whether the network event associated with the Asynchronous Select 
call is a socket-close event or an out-of-band data received event (step 141). In response to a positive determination 
in step 141 , the WinSock socket driver 1 9 will generate an XtAppAddlnputQ call in which the condition is specified as 
an XtlnputExceptMask "exception 0 mask (step 142). On the other hand, if the WinSock socket driver 19 makes a 
negative determination in step 141, it will sequence to step 143 to determine whether the network event associated 
with the Asynchronous Select call is a socket-accept event or a read readiness notification. In response to a positive 
determination in step 143. the WinSock socket driver 19 will generate an XtAppAddlnput() call in which the condition 
is specified as an XtlnputReadMask "read* mask (step 144). If the WinSock socket driver 19 makes a negative deter- 
mination in step 143, it will sequence to step 145 to determine whether the network event associated with the Asyn- 
chronous Select call is a completed-socket-connection notification or a write-readiness notification. In response to a 
positive determination in step 145, the WinSock socket driver 19 will generate an XtAppAddlnputQ call in which the 
condition is specified as an XtlnputWriteMask "write" mask (step 146). 

Following step 142, 144 or 146, or following step 145 if the WinSock socket driver 19 makes a negative determi- 
nation in that step, the WinSock socket driver 1 9 returns to the applications program 21 which issued the Asynchronous 
Select call, providing a return value which identifies the return as an acknowledgment to the Asynchronous Select call 
(step 147). 

Following step 147, the WinSock socket driver 19 will perform no further operations in connection with the Asyn- 
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chronous Select call until it receives a response from the XtAppAddinputQ call. It will be appreciated that it may perform 
operations in connection with other calls from the same or other applications programs 21, including other Asynchro- 
nous Select calls. In addition, it may cancel the monitoring operation by the XtAppAddlnputf) call by issuing an XtRem- 
ovelnput call in response to a subsequent Asynchronous Select call as described above in connection with step 140 
as described above. 

However, if the Unix/X Windows XtAppAddinputQ call provides a response to the WinSock socket driver 1 9 before 
the WinSock socket driver 19 cancels the monitoring operation, the WinSock socket driver 19 receives the response 
(step 150). Initially, the WinSock socket driver 19 will test a reentrant control flag to determine whether it is currently 
processing a response (step 1 51 ). If the WinSock socket driver 1 9 makes a positive determination in step 1 51 . it returns, 
in which case it will not accept the response from the Unix/XWindows XtAppAddinputQ call at that point. The operating 
system program will attempt to provide the response to the Unix/XWindows XtAppAddlnput() call response at a later 
point. 

If the WinSock socket driver 1 9 makes a negative determination in step 1 51 , it is not currently processing a response 
to the XtAppAddinputQ call. In that case, the WinSock socket driver 19 will sequence to step 152 to condition the re- 
entrant control flag to indicate that it is currently processing a response, and sequence to a series of steps to process 
the response and provide it to the applications program 21 . As described above, the response provided by the XtAp- 
pAddinputQ call corresponds to the client data parameter provided in the call itself, which in turn, identifies the type of 
socket event being monitored by the Unix/XWindows XtAppAddinputQ call. Accordingly, after receiving the response, 
the WinSock socket driver 19 will determine the type of response (step 153), and will generate a message idenfifiing 
the response (step 154) and post it in a response queue associated with the calling applications program 21 (step 
1 55). Thereafter, the WinSock socket driver 1 9 will condition the reentrant control flag to indicate that it is not currently 
processing a response, to enable it (the WinSock socket driver 1 9) to process another Xt AppAddtnput() call (step 1 56). 

While the operations performed by the WinSock socket driver 19 in performing non-blocking calls defined by the 
WinSock API in connection with the Unix/XWindows operating system program have been illustrated in connection 
with only two WinSock calls, namely the WinSock Synchronous Select call and the WinSock Asynchronous Select call, 
it will be appreciated that it may execute other calls in a similar manner. 

The invention provides a number of advantages. In particular, it provides a WinSock socket driver 1 9 that performs 
function calls under the Unix operating system program as defined by the WinSock specification in a non-blocking 
manner, as is preferred in connection with Windows application programming. 

The foregoing description has been limited to a specific embodiment of this invention. It will be apparent, however, 
that various variations and modifications may be made to the invention, with the attainment of some or all of the ad- 
vantages of the invention. It is the object of the appended claims to cover these and such other variations and modi- 
fications as come within the true spirit and scope of the invention. 
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1. IIVTROPUCTION 

1.1 What Is Windows Sockets? 

The Windows Sockets specific a rioa defines a oetwork programming interface for Microsoft Windows 1 
which is based oq the "socket" paradigm popularized in the Berkeley Software Distribution (BSD) from 
the University of California ac Berkeley. It encompasses both familiar Berkeley socket style routines and 
a set of Windows -specific extensions designed to allow the programmer to take advantage of the 
message-driven nature of Windows. 

The Windows Sockets Specification is Intended to provide a single API to which application developers 
can program and multiple network software vendors can conform. Furthermore, in the context of a 
particular version of iVGcrosoft Windows, it defines a binary interface (ABD such chat ah application 
written to the Windows Sockets API can work with a conformant protocol implementation from any 
network software vendor. This specification thus defines the library calls and associated semantics to 
which an application developer can program and which a network software vendor can implement. 

Network software which conforms to this Windows Sockets specification will be considered "Windows 
Sockets Compliant". Suppliers of interfaces which are "Windows Sockets Compliant" shall be referred to 
as "Windows Sockets Suppliers". To be Windows Sockets Compliant, a vendor must implement 100% of 
this Windows Sockets specification. 

Applications which are capable of operating with any "Windows Sockets Compliant" protocol 
implementation will be considered as having a "Windows Sockets Interface" and will be referred to as 
"Windows Sockets Applications". 

This version of the Windows Sockets specification defines and documents the use of the API in 
conjunction with the Internet Protocol Suite (IPS. generally referred to as TCP/IP)- Specifically, ail 
Windows Sockets implementations support both stream (TCP) and datagram (UDP) sockets. 

While the use of this API with alternative protocol stacks is not precluded (and is expected to be the 
subject of furore revisions of the specification), such usage is beyond the scope of this version of the 
specification. 

1.2 Berkeley Sockets 

The Windows Sockets Specification has been built upon the Berkeley Sockets programming model which 
is the de facto standard for TCP/IP networking. It is intended to provide a high degree of familiarity for 
programmers who are used to programming with sockets in UNIX 2 and other environments, and to 
simplify the task of porting existing sockets-based source code. The Windows Sockets API is consistent 
with release 4.3 of the Berkeley Software Distribution (4.3BSD). 

Portions of the Windows Sockets specification are derived from material which is Copyright (c) 1982- 
1986 by the Regents of the University of California. All rights are reserved. The Berkeley Software 
License Agreement specifies the terms and conditions for redistribution. 

1.3 Microsoft Windows and Windows-specific extensions 



1 Windows is a trademark of Microsoft Corporation. 

2 UNIX is a trademark of Unix System Laboratories. Inc. 
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This API is intended to be usable within ail implementations and versioos of Microsoft Windows from 
Microsoft Windows Version 3.0 onwards. It thus provides for Windows Sockets implementations and 
Windows Sockets applications in both L6 and 32 bit operating envLronmencs. 

Windows Sockets makes provisions for multithreaded Windows processes. A process contains oae or 
more threads of execution. In the Windows 3.1 n on -multi threaded world, a task corresponds to a process 
with a single thread. All references to threads in this document refer to actual 'threads'* In multithreaded 
Windows environments. In aon multithreaded environments (such as Windows 3.0). use of the term 
thread refers to a Windows process. 

The Microsoft Windows extensions included in Windows Sockets are provided to allow application 
developers to create software which conforms to the Windows programming model. It is expected that 
this will facilitate the Creadon of robust and high-performance applications, and will improve the 
cooperative multitasking of applications within non-preemptive versions of Windows. With the 
exception of WSAStartupO and WSACleanupO their use is not mandatory. 

1.4 The Status of this Specification 

Windows Sockets is an independent specification which was created and exists for the benefit of 
application developers and network vendors and. indirectly, computer users. Each published (non-draft) 
version of this specification represents a fully workable API for Implementation by network vendors and 
programming use by application developers. Discussion of this specification and suggested improvements 
continue and are welcomed. Such discussion occurs mainly via the Internet electronic mail forum 
winsock@micxodyne.com. Meetings of interested parties occur on an irregular basis. Details of these 
meetings are publicized to the electronic mail forum. 



1.5 Revision History 

1.5.1 Windows Sockets Version 1.0 

Windows Sockets Version 1.0 represented the results of considerable work within the vendor and user 
communiry as discussed in Appendix C. This version of the specification was released in order that 
nerwork sofrware suppliers and application developers could begin to construct implementations and 
applications which conformed to the Windows Sockets standard. 

1.5.2 Windows Sockets Version 1.1 

Windows Sockets Version 1.1 follows the guidelines and structure laid out by version 1.0. making 
changes only where absolutely necessary as indicated by the experiences of a number of companies that 
created Windows Sockets implementations based on the version 1.0 specific a don. Version 1.1 contains 
several clarifications and minor fixes to version 1.0. Additionally, the following more significant changes 
were incorporated into version 1.1: 

o Inclusion of the gethostnameO routine to simplify retrieval of the host's name and address. 

o Definition of DLL ordinal values below 1000 as reserved for Windows Sockets and ordinals 
above 1000 as unrestricted. This allows Windows Sockets vendors to include private interfaces 
to their DLLs without risking that the ordinals chosen will conflict with a furure version of 
Windows Sockets. 

o Addition of a reference count to WSAStarrupO and WSACleanupO. requiring 
correspondences between the calls. This allows applications and third-party DLLs to make use 
of a Windows Sockets implementation without being concerned about the calls to these APIs 
made by the other. 
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o Change of re aim type of inet_addr() from struct in_addr to unsigned long. This was ( 
required due to different handling of four-byte s true aire returns between the Microsoft and 
Borland C compilers. 

o Change of WSAAsyncSelect() semantics from "edge-triggered" to "level-triggered". The 
level -triggered semantics significandy simplify an application's use of this routine. 

o Change the ioctlsocketO FIOlVBIO semantics to fail if a WSAAsyocSelectO call is 
outstanding on the socket. 

o Addition of the TCP_N'ODELAY socket option for RFC 1 122 conformance. 
All changes between the 1.0 and 1. 1 specifications are flagged with change bars at the left of the page. 
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2. PROGRAMMING WITH SOCKETS 

2.1 Windows Sockets Stack Installation Checking 

To detect the presence of oae (or many) Windows Sockets Implementations oa a system, an application 
which has been Linked with the Windows Sockets Import Library may simply call the WSAStartupO 
routine. If an application wishes to be a little more sophisticated it can examine the SPATH environment 
variable and search for instances of Windows Sockets implementations (WTNSOCK.DLL). For each 
instance it can issue a LoadLibraryO call and use the WSAStartupO routine to discover implementation 
specific data. 

This version of the Windows Sockets specification does not attempt to address explicidy the issue of 
multiple concurrent Windows Sockets implementations. Nothing in the specification should be 
Interpreted as restricting multiple Windows Sockets DLLs from being present and used concurrendy by 
one or more Windows Sockets applications. 

For further details of where to obtain Windows Sockets components, see Appendix B.2. 

2.2 Sockets 

The following material is derived from the document "An Advanced 4.3BSD Interprocess Communication 
Tutorial" by Samuel J. Leffler. Robert S. Fabry. William N. Joy. Phil Lapsiey. Steve Miller, and Chris 
Torek. 

2.2.1 Basic concepts 

The basic building block for communication is the socket. A socket is an endpoint of communication to 
which a name may be bound. Each socket in use has a type and an associated process. Sockets exist 
within communication domains. A communication domain is an abstraction introduced to bundle 
common properties of threads communicating through sockets. Sockets normally exc han ge data only 
with sockets in the same domain (it may be possible to cross domain boundaries, but only if some 
translation process is performed). The Windows Sockets facilities support a single communication 
domain: the Internet domain, which is used by processes which communicate using the Internet Protocol 
Suite. (Future versions of this specification may include additional domains.) 

Sockets are typed according to the communication properties visible to a user. Applications are 
presumed to communicate only between sockets of the same type, although there is nothing that prevents 
communication between sockets of different types should the underlying co mmuni cation protocols 
support this. 

Two types of sockets currently are available to a user. A stream socket provides for the bi-directional, 
reliable, sequenced, and undu plicated flow of data without record boundaries. 

A datagram socket supports bi-directional flow of data which is not pro m ised to be sequenced, reliable, 
or undu plica ted. That is. a process receiving messages on a datagram socket may find messages 
duplicated, and. possibly, in an order different from the order in which it was sent. An important 
characteristic of a datagram socket is that record boundaries in data are preserved. Datagram sockets 
closely model the facilities found in many contemporary packet switched networks such as Ethernet. 

2.2.2 Client-server model 

The most commonly used paradigm in constructing distributed applications is the client/server model. In 
this scheme client applications request services from a server application. This Implies an asymmetry in 
establisning communication between the client and server. 
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The client and server require a well-known set of conventions before service may be rendered (and 
accepted). This set of conventions comprises a protocol which muse be Implemented at both ends of a 
connection. Depending on the situation, the protocol may be symmetric or asymmetric. In a symmetric 
protocol, either side may play the master or slave roles. In an asymmetric protocol, one side is 
immutably recognized as the master, with the other as the slave. An example of a symmetric protocol is 
the TELNET protocol used in the Internet for remote terminal emulation. An example of an asymmetric 
protocol is the Internet file transfer protocol. FTP. No matter whether the specific protocol used in 
obtaining a service is symmetric or asymmetric, when accessing a service there is a client process" and a 
"server process". 

A server application normally listens at a well-known address for service requests. That is. the server 
process remains dormant until a connection is requested by a client's connection to the server's address. 
At such a time the server process "wakes up" and services the client, performing whatever appropriate 
actions the client requests of it. V/hile connection -based services are the norm, some services are based 
on the use of datagram sockets. 

2.2.3 Out-of-band data 

Note: The following discussion of out -of -band data, also referred to as TCP Urgent data, follows the 
model used in the Berkeley software distribution. Users and implementors should be aware of the fact 
that there are at present two conflicting interpretations of RFC 793 (in which the concept is introduced), 
and that the Implementation of out-of-band data in the Berkeley Software Distribution does not conform 
to the Host Requirements laid down in RJFC 1 122. To minimize interoperability problems, applications 
writers are advised not to use out -of- band data unless this is required in order to Lnteroperate with an 
existing service. Windows Sockets suppliers are urged to document the out-of-band semantics (BSD or 
RFC 1 122) which their product implements. It is beyond the scope of this specification to mandate a 
particular set of semantics for out- of -band data handling. 



The stream socket abstraction includes the notion of "out of band" data. Out-of-band data is a logically 
independent transmission channel associated with each pair of connected stream sockets. Out-of-band 
data is delivered to the user independently of normal data. The abstraction defines that the out-of-band 
data facilities must support the reliable delivery of at least one out-of-band message at a time. This 
message may contain at least one byte of data, and at least one message may be pending delivery to the 
user at any one time. For communications protocols which support only in- band signaling (i.e. the 
urgent data is delivered in sequence with the normal data), the system normally extracts the data from the 
normal data stream and stores it separately. This allows users to choose between receiving the urgent 
data in order and receiving it out of sequence without having to buffer all the intervening data. It is 
possible to "peek'* at out-of-band data. 

An application may prefer to process out-of-band data "in-line**, as part of the normal data stream. This 
is achieved by setting the socket option SO„OOB INLINE (see section 4. 1.21. setsockoptO). In this case, 
the application may wish to determine whether any of the unread data is "urgent" (the term usually 
applied to in-line out-of-band data). To facilitate this, the Windows Sockets implementation will 
maintain a logical "mark" In the data stream indicate the point at which the out-of-band data was sent. 
An application can use the SIOCATMARK ioctlsocketO command (see section 4.1. 12) to determine 
whether there is any unread data preceding the mark. For example, it might use this to ^synchronize 
with its peer by ensuring that all data up to the mark in the data sire am is discarded when appropriate. 

The WSAAsyncSelectO tontine is particularly well suited to handling notification of the presence of out- 
of-band-data. 

2.2.4 Broadcasting 
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By using a datagram socket, it is possible to send broadcast packets oo many networks supported by the 
system. The network itself must support broadcast: the system provides qo simulation of broadcast in 
software. Broadcast messages can place a high load oq a network, since they force every host on the 
network to service them. Consequently, the ability to send broadcast packets has been limited to sockets 
which are explicidy marked as allowing broadcasting. Broadcast is typically used for one of two reasons: 
it is desired to find a resource on a local network without prior knowledge of its address, or important 
functions such as routing require that information be sent to all accessible aeighbors. 

The destination address of the message to be broadcast depends on the network(s) on which the message 
is to be broadcast. The Internet domain supports a shorthand flotation for broadcast on the local aecwork. 
the address EN AD DR .BROADCAST. Received broadcast messages contain the senders address and 
port, as datagram sockets must be bound before use. 

Some types of network support the nodon of different types of broadcast. For example, the EEEE 802.5 
token ring architecture supports the use of link-level broadcast indicators, which control whether 
broadcasts are forwarded by bridges. The Windows Sockets specification does not provide any 
mechanism whereby an application can determine the type of underlying network, nor any way to control 
the semantics of broadcasting. 

2.3 Byte Ordering 

The Intel byte ordering is like that of the DEC VAX 3 , and therefore differs from the Internet and 68000 4 - 
type processor byte ordering. Thus care must be taken to ensure correct oricntadon. 

Any reference to IP addresses or port numbers passed to or from a Windows Sockets routine must be in 
network order. This includes the IP address and port fields of a struct sockaddr_in (but not the 
sin ^family field). 

Consider an application which normally contacts a server on the TCP port corresponding to the "rime" 
service, but which provides a mechanism for the user to specify that an alternative port is to be used. The 
port number returned by getservbynameO is already in network order, which is the format required 
constructing an address, so no trans la don is required. However if the user elects to use a different port, 
entered as an Integer, the application must convert this from host to network order (using the htoosO 
function) before using it to construct an address. Conversely, if the application wishes to display the 
number of the port within an address (returned via. e.g.. gerpeeruameO). port number must be 
convened from network to host order (using ntohsO) before it can be displayed. 

Since the Intel and Internet byte orders are different, the conversions described above are unavoidable. 
Application writers are cautioned that they should use the standard conversion functions provided as part 
of the Windows Sockets API rather than writing their own conversion code, since future implementanons 
of Windows Sockets are likely to run on systems for which the host order is identical to the network byte 
order. Only applications which use the standard conversion functions are likely to be portable. 

2.4 Socket Options 

The socket options supported by Windows Sockets are listed in the pages describing setsockoptO and 
getsockoptO- A Windows Sockets implementation must recognize all of these options, and (for 
getsockoptO) return plausible values for each. The default value for each option is shown in the 
following table. 



3 VAX is a trademark of Digital Equipment Corporation. 

4 68000 is a trademark of Motorola. Inc. 
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Value 




Meaning ; Default 




I SO.ACCEPTCOiVN 


BOOL 


Socket is tistenQing. 


FALSE unless a 
listenQ has been 
performed 




SO.BROADCAST 


BOOL 


Socket is configured for the 
cransmissioa of broadcast 
messages. 


FALSE 




SCLDEBUG 


BOOL 


Debugging is enabled. 


FALSE 


(i) 


SO.DONTLINGER 


BOOL 


If true, the SO_ LINGER option 
is disabled. 


TRUE 




so.dontroute 


BOOL 


Routing is disabled. 


FALSE 


(i) 


SO_ERROR 


Lai 


Recrieve error scams and clear. 


0 




SO.KEEPALrVE i BOOL 


Keepalives are being sent. 


FALSE 




SO_LtNGER 


srruct linger 
FAR - 


Returns the current linger 
options. 


ionoffls 0 




SO JDOB INLINE 


BOOL 


Out-of-band data is being 

(wCIVCU LU LUC LiVJl LU aJL da L3 

stream. 


FALSE 




SO.RCVBUF 


Lot 


Buffer size for receives 


Implementation 
dependent 


(0 


SO.REUSEADDR 


BOOL 


The address to which this socket 
is bound can be used by others. 


FALSE 




SO.SNDBUF 


inc 


Buffer size for sends 


Implementation 
dependent 


(i) 


SOJTYPE 


inc 


The type of the socket (e.g. 
SOCKLSTREAM). 


As created via 
socketO 




TCP_NODELAY 



BOOL 


Disables the Nagle algorithm 
for send coalescing. 


Implementation 
dependent 





Notes: 

(i> An implementation may silently ignore this option on setsockoptO and return a 

constant value for getsockoptO. or it may accept a value for setsockoptO and return the 
corresponding value in getsockoptQ without using the value in any way. 



2.5 Database Files 

The getXbjYO 3 and WSAAsyncGetXBy Y0 classes of routines axe provided for retrieving network 
specific information. The getXby Y0 routines were originally designed (in the first Berkeley UNIX 
releases) as mechanisms for looking up information in text databases. Although the information may be 
retrieved by the Windows Sockets implementation in different ways, a Windows Sockets application 
requests such information in a consistent manner through either the getXbyYO or the 
WSAAsyncGetXByYO class of routines. 

2.6 Deviation from Berkeley Sockets 

There are a few limited instances where the Windows Sockets .API has had to divert from strict adherence 
to the Berkeley conventions, usually because of difficulties of implementation in a Windows 
environment. 



5 This specification uses the function name getXbyYO to represent the set of routines gethdstbyaddrO. 
gethostbynameO. etc. Similarly WSAAsvncGetXByYO represents WSAAsyncGetHostByAddrQ. etc. 
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2.6.1 socket data type and error values 

A new daca rype. SOCKET, has been defined. The definition or this cype was accessary for future 
enhancements to the Windows Sockets specification, such as being able to use sockets as fde handJes in 
Windows NT 6 . Definition of this type also facilitates porting of applications to a Winy 3 2 environment, as 
the type will automatically be promoted from 16 to 32 bits. 

In UNIX, all handles, including socket handles, are small, aon-negative integers, and some applications 
make assumptions that this will be true. Windows Sockets handles have no restrictions, other than chat 
the value INVAL ID _SOCKET is not a valid socket. Socket handles may take any value in the range 0 to 
INVAIJD_S0CKET-1. 

Because the SOCKET type is unsigned, compiling existing source code from, for example, a UNIX 
environment may lead to compiler warnings about signed/unsigned data type mismatches. 

This means, for example, that checking for errors when the socketO and acceptO routines return should 
001 be done by comparing the return value with -1. or seeing if the value is negative (both common, and 
legal, approaches in BSD). Instead, an application should use the manifest constant INVAL ED_SOGQET 
as defined in winsock.b. For example: 
TYPICAL BSD STYLE: 

3 = 'socket (...); 

if (s =- -1) /* or 3 < 0 */ 

{ . . . » 

PREFERRED STYLE: 

3 - socket (...); 
if (s " INVAL ID_SOCKET) 
{'.-.} 

2.6.2 selectO and FD_* 

Because a SOCKET is no longer represented by the UNIX-style "small. non-negative integer'*, the 
implementation of the selectO function was changed in the Windows Sockets APL Each set of sockets is 
still represented by the fd.set rype. but instead of being stored as a bitmask the set is implemented as an 
array of SOCKETS. To avoid potential problems, applications mu^ adhere to the use of the FD_XXX 
macros to set. initialize, clear, and check the fd_set structures. 

2.6.3 Error codes - errno, h_errno & WSAGetLastErrorO 

Error codes set by the Windows Sockets implementation are NOT made available via the errno variable. 
Additionally, for the getXby YQ class of functions, error codes are NOT made available via the h_errno 
variable. Instead, error codes are accessed by using the WSAGetLastErrorO API described in section 
4.3. 11. This function is provided in Windows Sockets as a precursor (and eventually an alias) for the 
Win32 function GetLastErrorO- This is intended to provide a reliable way for a thread in a multi- 
threaded process to obtain per- thread error information. 

For compatibility with BSD, an application may choose to include a line of the form; 
#define errno wSAGet LastError ( ) 

This will allow networking code which was written to use the global errno to work correcdy in a single- 
threaded environment. There are. obviously, some drawbacks. If a source file includes code which 
inspects errno for both socket and nan- socket functions, this mechanism canned be used. Furthermore, it 
is not possible for an application to assign a new value to errno. (In Windows Sockets the function 
WSASetLastErrorO may be used for this purpose.) 



NT and Windows/NT are trademarks of Microsoft Corporation. 
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TYPICAL BSD STYLE: 

r = :ecv (...); 
if (c — -1 

S& er mo == I WOULD BLOCK) 
(...) 

PREFERRED STYLE: 

r = recv (...); 

if (c « -I / * (buc see below) */ 

S& WSAGetLasc£rror () « EWOULDBLOCK) 
(...) 

Although error constants consistent with 4.3 Berkeley Sockets are provided for compatibility purposes, 
applications should, where possible, use the "WSA" error code definitions. For example, a more accurate 
version of the above source code fragment is: 

r = recv (...); 

it (r ~ -1 /* (but see below) »/ - 

&& WSAGecLascError C) ~~ WSAEWOULDBLOCK) 
(...) 

2.6.4 Pointers 

All pointers used by applications with Windows Sockets should be FAR. To facilitate this, data type 
definitions such as LP HO STENT are provided. 

2.6.5 Renamed functions 

In two cases it was necessary to rename functions which are used in Berkeley Sockets in order to avoid 
clashes with other APIs. 

2.6.5.1 close() & ciosesocketO 

In Berkeley Sockets, sockets are represented by standard file descriptors, and so the closeO function can 
be used to close sockets as well as regular files. While nothing in the Windows Sockets API prevents an 
implementation from using regular file handles to identify sockets, nothing requires it either. Socket 
descriptors are not presumed to correspond to regular file handles, and file operations such as readO- 
writeO. aad closeO cannot be assumed to work correctly when applied to sockets. Sockets must be 
closed by using the ciosesocketO routine. Using the closeO routine to close a socket is incorrect and the 
effects of doing so are undefined by this specification. 

2.6.5.1 ioctIO & ioctlsocketO 

Various C l an g ua ge run- time systems use the ioctiO routine for purposes unrelated to Windows Sockets. 
For this reason we have defined the routine ioctlsocketO which is used to handle socket functions which 
in the Berkeley Software Distribution are performed using ioctIO and fcntlO- 

2.6.6 Blocking routines & EINPROGRESS 

Although blocking operations on sockets are supported under Windows Sockets, their use is strongly 
discouraged. Programmers who are cons trained to use blocking mode - for example, as pan of an 
existing application which is to be ported - should be aware of the semantics of blocking operations Ln 
Windows Sockets. See section 3.1.1 for more details. 

2.6.7 Maximum number of sockets supported 

The maximum number of sockets supported by a particular Windows Sockets supplier is implementation 
specific. An application should make no assumptions about the availability of a certain number of 
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sockets. This topic is addressed further in section 4.3. L 5. WSAStartupQ However, independent of the 
dumber of sockets supported by a particular implementation is the issue of the maximum number of 
sockets which an application can actually make use of. 

The maximum number of sockets which a Windows Sockets application can make use of is determined at 
compile time by the manifest constant FD_ SET SIZE. This value is used in constructing the fd_set 
struccures used in selectO (see section 4.1. IS). The default value in winsock-h is 64. If an application is 
designed to be capable of working with more than 64 sockets, the implementor should define the 
manifest FD_ SET SIZE in every source fde before including wiosock.h. One way of doing this may be to 
include the definition within die compiler options in the makefile, for example adding • 
DFD_SETSIZE= 128 as an option to the compiler command line for Microsoft C. It must be emphasized 
that defining FD.SETSIZE as a particular value has no effect on the actual number of sockets provided 
by a Windows Sockets implementation. 

2.6.8 Include files 

For ease of portability of existing Berkeley sockets based source code, a number of standard Berkeley 
include fiJcs are supported. However, these Berkeley header files merely include the winsock.h include 
file, and it is therefore sufficient (and recommended) that Windows Sockets application source files 
should simply Include wiasockJi. 

2.6.9 Return values on API failure 

The manifest constant SOCKET_ERROR is provided for checking API failure. Although use of this 
constant is not mandatory, it is recommended. The following example illustrates the use of the 
SOCKET.ERROR constant: 

TYPICAL BSD STYLE: 

r = recv( . . . ) ; 

if (r — -1 /' or r < 0 -/ 

££ errno — ZWOULDBLOCK) 
(...) 

PREFERRED STYLE: 

r - recv (...); 

if (r — SOCKET_£RROR 

&& WSAGetLaatError () ==» WSAE WOULD BLOCK) 
(...) 

2.6.10 Raw Sockets 

The Windows Sockets specification does not mandate that a Windows Sockets DLL support raw sockets, 
that is. sockets opened with SOCK_RAW. However, a Windows Sockets DLL is allowed and 
encouraged to supply raw socket support. A Windows Sockets-compliant application that wishes to use 
raw sockets should attempt to open the socket with the socketO call (see section 4. 1.23). and if it fails 
either attempt to use another socket type or indicate the failure to the user. 

2.7 Windows Sockets In Multithreaded Versions of Windows 

The Windows Sockets interface is designed to work for both single- threaded versions of Windows (such 
as Windows 3.1) and preemptive multithreaded versions of Windows (such as Windows NT). In a 
multithreaded environment the sockets interface is basically the same, but the author of a multithreaded 
application must be aware that it is the responsibility of the application, not the Windows Sockets 
implementation, to synchronize access to a socket between threads. This is the same nil* as applies to 
other forms of I/O such as file I/O. Failure to synchronize calls on a socket leads to unpredictable results; 
for example if there are two simultaneous calls to sendO, there is no guarantee as to the order in which 
the data will be sent. 
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Closing a socket In oae thread that has an outstanding bloc long call on the same socket in another thread 
will cause the blocking call to fail with WSAHNTR. just as if the operation were canceled. This also 
applies if there is a select () call outstanding and the application closes one of the sockets being selected. 

There is no default blocking hook ins tailed in preemptive multithreaded versions of Windows. This is 
because the machine will not be blocked if a single application is waiting for an operation to complete 
and hence not calling Peek Messaged} or GetMessageO which cause the application to yield. in 
nonprempuve Windows. However, for backwards compatibility the WSASetBIockiogHookO call is 
implemented in multithreaded versions of Windows, and any application whose behavior depends on the 
default blocking hook may install their own blocking hook which duplicates the default hook s semantics, 
if desired. 
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3. SOCKET LIBRARY OVERVIEW 
3.1 Socket Functions 

The Windows Sockets specification includes the following Berkeley-style socket murine- 



acceptO • 


An incoming connection is acknowledged and associated 
with an immediately ere a led socket. The original socket is 
returned to the listening state. 


biodO 


Assign a locaJ name to an unnamed socket. 


closesocketO * 


Remove a socket from the per-process object reference 
table. Only blocks if SO LINGER is set. 


coanect(j 


Initiate a connection on the specified socket. 


getpeemameO 


Retrieve the name of the peer connected to the specified 
socket. 


getsoc k nam e0 


Retrieve the current flame for the specified socket 


getsockoptO 


Retrieve options associated with the specified socket. 


htoolO 




Convert a 3 2- bit quantiry from host byte order to network 
byte order. 


btoosO 


Convert a 1 6-bit quantity from host byte order to network 
byte order. 


LQei_aoaru 


Converts a character string representing a number Ln 
ujiciuci 5iauuAru aouuou io an internet aufire^s vqiu£ 


inet^ntoaO 


Converts an Internet address value to an ASCII string in 
notation i.e. "a.b.c.d". 


ioctlsocketO 


Provide control for sockets. 


Us tea 0 


Listen for incoming connections on a specified socket. 


otohJO 


Convert a 32-bit quantiry from network byte order to host 
byte order. 


atohsO 


Convert a 16-bit quantity from network byte order to host 
byte order. 


recvQ • 


Receive data from a connected socket. 


recvfromO * 


Receive data from either a connected or uncr>nnr«rted 
socket. 


selectO * 


Perform synchronous I/O multiplexing. 


sendQ • 


Send data to a connected socket. 


seadtoO * 


Send data to either a connected or unconnected socket. 


setsockoptO 


Store opticas associated with the specified socket- 


shutdowTiO 


Shut down part of a full -duplex connection- 


socketQ 


Create an endpoint for communication and return a socket 



* = The routine can block if acting on a blocking socket. 



3.1.1 BlockJng/Non blocking & Data Volatility 

One major issue in porting applications from a Berkeley sockets environment to a Windows environment 
involves "blocking"; that is. invoking a function which does not return until the associated operation is 
completed. The problem arises when the operation may f«k* an arbitrarily long rim* to complete: an 
obvious example is a recvO which may block until data has been received from the peer system. The 
default behavior within the Berkeley sockets model is for a socket to operate in a blocking mode unless 
the programmer explicitly requests that operations be treated as a on-blocking. // is strongly 
recommended that programmers use the nonblocJcing (asynchronous) operations if at all possible, as 
they work significandy better within the nonpreemptive Windows environment Use blocking 
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operations only if absolutely necessary, and carefully read and understand this section if you must use 
blocking operations. 

Even oa a blocking socket, some operations (e.g. bindO. getsockoptO- getpecrnameO) can be completed 
immediately. For such operations there is ao difference between blocking and non-blocking operation. 
Other operations (e.g. recv()) may be completed immediately or may take an arbitrary time to complete, 
depending on various transport conditions. When applied to a blocking socket, these operauoas are 
referred to as blocking operauoas. Ail routines which can block are listed with an asterisk in the tables 
above and below. 

Within a Windows Sockets implementation, a blocking ope radon which cannot be completed 
immediately is handled as follows. The DLL initiates the operadon. and then enters a loop In which it 
dispatches any Windows messages (yielding the processor to another thread if necessary) and then checks 
for the completion of the Windows Sockets function. Lf the function has completed, or if 
WSACanceLBlockiogCailO has been invoked, the blocking function completes with an appropriate 
result. Refer to section 4.3.13. WSASetBlockingHookO. for a complete description of this mechanism, 
including pseudocode for the various functions. 

If a Windows message is received for a process for which a blocking operation is La progress, there is a 
risk that the application will attempt to issue another Windows Sockets call. Because of the difficulty of 
managing this condition safely, die Windows Sockets specification does not support such application 
behavior. Two functions are provided to assist the programmer in this situation. WSAlsBlockingO may 
be called to determine whether or not a blocking Windows Sockets call is in progress. 
WSACanceLBlockingCallO may be called to cancel an Ln- progress blocking call, Lf any. Any other 
Windows Sockets function which is called m this situation will fail with the error WSAFTAfPRQQRESS- 
It should be emphasized that this restriction applies to both blocking and non-blocking operations. 

Although this mechanism is sufficient for simple applications, it cannot support the complex message- 
dispatching requirements of more advanced applications (for example, those using the MDI model). For 
such applications, the Windows Sockets API includes the function WSASetBlockingHookO. which 
allows the programmer to define a special routine which will be called instead of the default message 
dispatch routine described above. 

The Windows Sockets DLL calls the blocking hook only if all of the following are true: the routine is one 
which is defined as being able to block, the specified socket is a blocking socket, and the request cannot 
be completed immediately, (A socket is set to blocking by default, but the IOCTL FIONBIO and 
WSAAsyncSelectO both set a socket to nonlocking mode.) If an application uses only non-blocking 
sockets and uses the WSAAsyncSelectO and/or the WSAAsyncGetXBjYO routines instead of select 0 
and the getXby Y0 routines, then the blocking hook will never be called and the application does not 
need to be concerned with the reeatrancy issues the blocking hook can introduce. 

If an application invokes an asynchronous or non-blocking operation which takes a pointer to a memory 
object (e.g. a buffer, or a global variable) as an argument, it is the responsibility of the application to 
ensure that the object is available to the Windows Sockets implementation throughout the operation. The 
application must not invoke any Windows function which might affect the mapping or addressability of 
the memory involved. Ln a multithreaded system, the application is also responsible for coord in a ring 
acc e ss to the object using appropriate synchronization mechanisms. A Windows Sockets implementation 
cannot, and will not. address these issues. The possible consequences of failing to observe these rules are 
beyond the scope of this specification. 

3.2 Database Functions 

The Windows Sockets specification defines the following "database" routines. As noted earlier, a 
Windows Sockets supplier may choose to implement these in a manner which does not depend on local 
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database files. The pointer returned by certain database routines such as gethostbynameO points to a 
structure which is allocated by the Windows Sockets library. The data which is pointed to is volatile and 
is good only undi the aext Windows Sockets API call from that thread. Additionally, the application 
must never attempt to modify this s true aire or to free any of its components. Only one copy of thi* 
structure is allocated for a thread, and so the application should copy any information which it needs 
before issuing any other Windows Sockets API calls. 



gethostbyaddrO " 


Retrieve the name(s) and address corresponding to a 
network address. 


get host by □ am e0 • 


Retrieve the name(s) and address corresponding to a host 
name. 


geLbostnameO 


Retrieve the name of the local host. 


get pro toby nam e0 * 


Retrieve the protocol name and number corresponding to a 
protocol name. 


getprotobynumberO * 


Retrieve the protocol name and number corresponding to a 
protocol number. 


getservbynameO * 


Retrieve the service name and port corresponding to a 
service name. 


getservbyportO * 


Retrieve the service name and port corresponding to a 
port. 







* = The routine can block under some circumstances. 



3.3 Microsoft Windows-specific Extension Functions 

The Windows Sockets specification provides a number of extensions to the standard sec of Berkeley 
Sockets routines. Principally, these extended APIs allow message-based, asynchronous access to network 
events. While use of this extended API set is not mandatory for socket-based programming (with the 
exception of WSAStartupO and WSACIeanupO). it is recommended for conformance with the 
Microsoft Windows programming paradigm. 
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WSAAsvocGetHosLB vAddrQ 



WSAAsvacGetHostB yNameO 



WSAAsvDcGelProtoBvNaiDeO 
WSAAsvncGetProtoByNumberQ 



WSAAsvacGetServBvNameQ 



WSAAsvncCetServBvPortQ 



A sec of functions which provide asynchronous 
versions of the standard Berkeley 
getXby YO functions. For example, the 
WSAAsyncGetHostByNanieO function provides an 
asynchronous message based implementation of 
the standard Berkeley gethostbvnameQ function. 



WSAAsvncSelectQ 



W S A C an ce IA s y a c R eq u est 0 



Perfonn asynchronous version of selectQ 



Cancel an outstanding instance of a 
WSAAsypcGetXBy YQ function. 



WSACanceiBlockingCaJlO 



Cancel an outstanding "blocking" API call 



WSACleanupQ 



WSAGetLastErrorQ 
WSAIsBIockingO 



Sign off from the underlying Windows Soriwg DLL, 



Obtain details of last Windows Sockets API error 



WSASetBlockingHookQ 



Ctetermine if the underlying Windows Sockets DLL is 
already bloc king an exitin g call for this thread 



WSASeLLasUErrorO 



'Hook" the blocking method used by the underlying 
Windows Sockets implementation 



WSAStartupQ 



Set the error to be returned by a subsequent 
WSACetLastErrorQ 



Initialize the underlying Windows Sockets DLL 



WSAUnhookBtockipgHookO 



Restore the original blocking function 



3.3.1 Asynchronous select() Mechanism 

The WSAAsyncSelectO API allows an application to register an interest in one or many network events 
This API is provided to supersede the need to do polled network I/O. Any situation in which select 0 or ' 
non-blocking IAD routines (such as sendO and recvO) are either already used or are being considered is 
usually a candidate for the VVSAAsyncSelectO API. When declaring interest in such condition(s) you 
supply a window handle to be used for notification. The corresponding window then receives message- 
based notification of the conditions in which you declared an interest. 

WSAAsyucSelectO »Uows interest to be declared in the following conditions for a particular socket- 
Socket readiness for reading 
Socket readiness for writing 
Out-of-band data ready for reading 
Socket readiness for accepting incoming connection 
Completion of non-blocking conaectO 
Connection closure 

3.3.2 Asynchronous Support Routines 

The asynchronous -database'' functions allow applications to request information in an asynchronous 
manner. Some network implementations and/or configurations perform network based operations to 
resolve such requests. The WS AAsvdcG etXBy YO functions allow application developers to request 
services which would otherwise block the operation of the whole Windows environment if the standard 
Berkeley function were used. The WSACanceUsyncRequestO function allows an application to cancel 
any outstanding asynchronous request. 

3.3.3 Hooking Blocking Methods 

As noted in section 3.1.1 above. Windows Sockets implements blocking operations in such a way that 
Windows message processing can continue, which may result in the application which issued the call 
receiving a Windows message. In certain situations an application may want to influence or change the 
way in which this pseudo-blocking process is implemented. The WSASetBlockingHookQ provides the 
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abiliry to substitute a named routine which the Windows Sockets Lm piemen cation is to use when 
relinquishing the processor during a "blocking" operation. 

3.3.4 Error Handling 

For compatibility with thread-based environments, details of APE errors are obtained through the 
WSAGetLastErrorO API. .Although the accepted "Berkeley-Style" mechanism for obtaining socket- 
based aetwork errors is via "errao". this mechanism cannot guarantee the integrity of an error ED La a 
oquIu- threaded environment. WSAGetLastErrorO allows you to retrieve an error code on a per thread 

basis. 

WSAGetLastErrorO returns error codes which avoid conflict with standard Microsoft C error codes. 
Certain error codes returned by certain Windows Sockets routines fail into the standard range of error 
codes as defined by Microsoft C If you are NOT using an application development environment which 
defines error codes consistent with Microsoft C. you are advised to use the Windows Sockets error codes 
prefixed by "WS A" to ensure accurate error code detection. 

Mote that this specification defines a recommended set of error codes, and lists die possible errors which 
may be returned as a result of each function. It may be the case in some implementations that other 
Windows Sockets error codes will be returned in addition to those listed, and applications should be 
prepared to handle errors other than chose enumerated under each API description. However a Windows 
Sockets implementation must not return any value which is not enumerated in the table of legal Windows 
Sockets errors given in Appendix A. 1. 

3.3.5 Accessing a Windows Sockets DLL from an Intermediate DLL 

A Windows Sockets DLL may be accessed both directly from an application and through an 
"intermediate" DLL. An example of such an intermediate DLL would be a virtual network API layer that 
supports generalized network functionality for applications and uses Windows Sockets. Such a DLL 
could be used by several applications simultaneously, and the DLL must take special precautions with 
respect to the WSAStartupO and WSACIeanupO calls to ensure that these routines are called in the 
context of each task that will make Windows Sockets calls. This is because the Windows Sockets DLL 
will need a call to WSAStartupO for each task in order to set up task- specific data structures, and a call 
to WSACIeanupO to free any resources allocated for the f*sk. 

There are (at least) two ways to accomplish this. The simplest method is for the intermediate DLL to 
have calls similar to WSAStartupO and WSACIeanupO that applications call as appropriate. The DLL 
would then call WSAStartupO or WSACIeanupO from within these routines. Another mechanism is 
for the intermediate DLL to build a table of task handles, which are obtained from the 
GetCurrentTaskO Windows API and at each entry point into the intermediate DLL check whether 
WSAStartupO has been called for the current task, then call WSAStartupO if necessary. 

If a DLL makes a blocking call and does not install its own blocking hook. rh*»n the DLL author must be 
aware that control may be returned to the application either by an application- installed blocking hook or 
by the default blocking hook. Thus, it is possible that the application will cancel the DLL's blocking 
operation via WSACancelBlockiogCallO. If this occurs, the DLL's blocking operation will fail with the 
error code WSAFIKl K. and the DLL must return control to the calling task as quickly as possible, as the 
used has Likely pressed a cancel or close button and the task has requested control of the CPU. It is 
recommended that DLLs which make blocking calls install their own blocking hooks with 
WSASetBlockingHookO to prevent unforeseen inter actions between the application and the DLL. 

Note that this is not necessary for DLLs in Windows NT because of its different process and DLL 
structure. Under Windows NT. the intermediate DLL could simply call WSAStartupO ui its DLL 
initialization routine, which is cj\ 1 led whenever a new process which uses the DLL starts. 



33 



EP 0 770 958 A1 



Socket Library Overview 1 7 

3.3.6 Internal use of Messages by Windows Sockets Implementations 

In order to implement Windows Sockets purely as a DLL, it may be necessary for the DLL to post 
messages Internally for communication and timing. This is perfectly legal; however, a Windows Sockets 
DLL must not post messages to a window handle opened by a client application except for those 
messages requested by the application. A Windows Sockets DLL that needs to use messages for its own 
purposes must open a hidden window and post any necessary messages to the handle for that window. 

3.3.7 Private API Interfaces 

The win sock. def file in Appendix B.7 lists the ordinals defined for the Windows Sockets APIs. In 
addition to the ordinal values listed, ail ordinals 999 and below are reserved for future Windows Sockets 
use. It may be convenient for a Windows Sockets implementation to export additional, private interfaces 
from the Windows Sockets DLL. This is perfectly acceptable, as long as the ordinals for these exports 
are above 1000. Note that any application that uses a particular Windows Sockets DLL's private APIs 
will most Likely not work on any other vendor's Windows Sockets implementation. Only the APIs 
defined in this document are guaranteed to be present in every Windows Sockets implementation. 

If an application uses private interfaces of a particular vendor's Windows Sockets DLL. it is 
recommended that the DLL not be statically linked with the application but rather dynamically loaded 
with the Windows routines LoadLibraryO and GetProcAddressO. This allows the application to give 
an informative error message if it is run on a system with a Windows Sockets DLL that does not support 
the same set of extended functionality. 



Socket Library Reference 18 



4. SOCKET LIBRARY REFERENCE 
4.1 Socket Routines 

This chapter presents the socket library routines in alphabetical order, and describes each routine in 
detail. 

In each routine it is indicated thai the header file winsock.h must be included. Appendix A. 2 Lists the 
Berkeley-compatible header Fdes which are supported. These are provided for compatibility purposes 
only, and each of them will simply include winsock.b. The Windows header File windows,h is also 
needed, but winsock.h will include it if necessary. 
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48- 



4.1.1 acceptQ 

Description Accept a connection on a socket 
^include <wtajockJ|> 



SOCKET PASCAL FAR accept ( SOCKET /« struct sockaddr FAR • addr, 
rot FAR • addriM ); 



f A descriptor identify ing i tocket which U listening for rannnrrions 

after a listen 0- 

addr An optional polnmr to t buffer which receives the address of the 

rnnn^nng entity, as known to coo miniminiri firms layer. The exact 
format of flv> addr tfpi Hf flf is determined by the address family 
strahlithM wben cbe socket was crested. 

addrUn An optional pointer to sn integer which rnrffsim the length of the 

edrircy* addt. 



Remarks This rouane extracts the first connection oo che queue of pendin g ran aerri oas oa 
creates » new socket with the sea* properties es J and returns a handle to the new 

SOCkeC If PIT r^-'K-g "^^ft^n *m tflfj thg xrrJegt it not 

marked as aoft-biockmg. ncceptO blocks cbe caller nadi e egnnerrion ia ntescnt, If che 
socket is marked aoo-blocidsg sod no pt^^^g connections en present on (he queoe* 
acceptO mams an error es described below. The ■crrrued socket may not be used co 
accept more connections. The ortgtaei socket remaini open. 

The argument addr is a icsult pifsineesr that is filled in wich the address of the 
connecting enQcy . es know co she communications layer- The exact tames of che addr 
paxatneas- is dcszrmined by the address family in which the comnitTntrarioo is 
asourmg. The oddrttviis t vafri^ result psrimeien k should inioWly contain che 
amount of space poioted co by addn on return it will contain che actual length On bytes) 
of che address returned. This call is used with cennocnon-hes^ sociat types siith as 
SOCK_STR£-AM. U addr tad/oraddrUn arc equal to NULL, then oo infoooanon 
about the r emcee address of the a cce paad socket is reamed. 



Return Value U no enor occurs, acceptO returns a vaJbe of cype SOQCET which it a descriptor for 
cbe accepted packet. Otherwise* a value of ISVAUD_SOCXET is nrmmnrf. and e 
specific error code may he reoievwi by ^« WSAGetf gsrPlrrorQ. 

The integer referred to by addrUn inidaily cant tint the amomtt of space p o i n ted to by 
oddr. On return it will *-~**\\* [be length in bytes of the address rammed. 

Error Code* WSANOTTNTTlALISED A staxsxsful WSAStartapO oust occur befexe 

^yiff^j (bis API. 

WSaQJETOOWN The Windows Sockets imp l rffirfi tation has defgrt e d 

chat che network subsystem has failed. 

WSAEFAULT The addrkn argumrm is coo snail (less chan che 

sizeof a struct socimddr). 
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WSAEINTR 

WSAEENPROGRESS 
WSAETNVAL 
WS AEMFTLE 

WSAENOBUFS 

WSAENOTSOCK 

WSAEOPNOTSUPP 

WS AEWOULDB LOCK 



The (blocking) call was canceled via 
WSACancelBIoclcingCallO. 

A blocking Windows Sockets call is in progress. 

tfstenO was not invoked prior to acceptO. 

The queue is empty upon en cry to acceptO and there 
are no descriptors available. 

No buffer space is available. 

The descriptor is not a socket. 

The referenced socket is not a type that supports 
connection -oriented service. 

The socket is marked as non-blocking anrf ao 
connections are present to be accepted. 



See AJso 



bindQ. connectQ. listenQ. select 0. socketO. WSAAsyncSelectQ 
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4.1.2 blnd() 

Description Associate a local address with a socket, 
"include <wiasock.h> 

int PASCAL FAR bind ( SOCKET s t const struct sockaddr FAR • name, int 
namelen ); 

s A descriptor identifying an unbound socket. 

name The address to assign to the socket. The sockaddr structure is defined 

as follows: 

struct aockaddr ( 

u_shorc 3a_farnily ; 

char sa_daca [ 14 j ; 



namelen The length of the name. 

Remarks This routine is used on an unconnected datagram or scream socket, before subsequent 

counectOs or listen 0s. When a socket is created with socketO. it exists in a name 
space (address family), but it has no name assigned. bindO establishes the local 
association (host address/port number) of the socket by assigning a local name to an 
unnamed socket. 

In the Internet address family, a name consists of several components. For 
SOCK_DGRAM and SOGC_ STREAM, the name consists of three pans: a host address, 
the protocol number (set implicidy to UDP or TCP. respectively), and a port number 
which identifies the application. If an application does not care what address is 
assigned to it it may specify an Internet address equal to IN ADD R_ ANY. a port equal 
to 0. or both. If the Internet address is equal to INAJDDR_ANY. any appropriate 
network interface will be used; this simplifies application programming in the presence 
of multi-homed hosts. If the port is specified as 0. the Windows Sockets 
implementation will assign a unique port to the application with a value between 1024 
and 5000. The application may use getsocknameO after bindO to learn the address chat 
has been assigned to it. but note that getsocknameO will not necessarily fill in the 
Internet address until the socket is connected, since several Internet addresses may be 
valid if the host is multi-homed. 

If an application desires to bind to an arbitrary port outside of the range 1024 to 5000, 
such as the case of rsh which must bind to any reserved pore code similar to the 
following may be used: 

SOCXADDR_IN 3 in; 
SOCKET 3; 

u_3hort alport - I ?PORT_RE SERVED; 

sin . sin_faraily - Ar_ItfET; 
sin. sin^addLr . 3_addr - 0/ 
for (; ; ) { 

s in . a in^port - htons (alport ) ; 

if (bind<3, ( L? SOCKADDR) £ 3 in, aizeof (sin)) « 0) { 
/* ic worked */ 
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if { GecLascError ( ) - WSAEADDRINUSE) { 
/' fail •/ 

} 

alport--; 

if (alport " I?PORT_aES£RVZD/2 ) { 

/* fail--all una 5 5 igned reserved pores are * / 
/• in use. */ 

\ 

} 



Return Value If no error occurs. bindO returns 0. Otherwise, it returns SOCKET_ERROR. and a 
specific error code may be retrieved by calling WSAGetLastEnrorO. 



Error Codes 



WS ANOTTNTTIALISED 

WSAENETDOWN 

WSAEADDRINUSE 

WSAJEFAULT 

WSAEINPROGRESS 
WSAEAFNOSUPPORT 

WSAETNVAL 

WSAENOBUFS 

WSAENOTSOCK 



A successful WSAStartupO must occur before 

lining thic API. 

The Windows Sockets Implementation has detected 
drat the network subsystem has failed. 

The specified address is already in use. (See the 
SCLREUSEADDR socket option under 
setsockoptO) 

The name ten argument is too small (less than the 
size of a struct sockaddr). 

A blocking Windows Sockets call is in progress. 

The specified address family is not supported by this 
protocol. 

The socket is already bound to an address. 

Not enough buffers available, too many connections. 

The descriptor is not a socket. 



See Also 



connectO. listenO. getsocknameO. setsockoptO. socketO. 
WSACancelBlockingCallQ. 
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4.1.3 closesocket() 

Description Close a socket. 



^include <wiosock.h> 

int PASCAL FAR closesocket ( SOCKET s ); 



s A descriptor identifying a socket. 

Remarks This function closes a socket. More precisely, it releases the socket descriptor s. so that 

further references to J will fail with the error WSAENOTSOCK. If this is the last 
reference to the underlying socket, the associated naming information and queued data 
are discarded. 

The semantics of ciosesocketO are affected by the socket options SO .LINGER and 
SO_DONTLINGER as follows: 



Option. 



Interval. 



TypC Of Close Wait for close? 



SO.DONTLINGER 

SO.LINGER 

SCLLINGER 



Don't care 
Zero 

Non-zero 



Graceful 

Hard 

Graceful 



No 
No 
Yes 



If SOILING ER is set (i.e. the t_pnoff field of the linger structure is non-zero; see 
sections 2.4. 4. 1.7 and 4. 1.21) with a zero timeout interval (IJinger is zero). 
ciosesocketO is not blocked even if queued data has not yet been sent or acknowledged. 
This is called a "hard M or "abortive" close, because the socket's virtual circuit is reset 
immediately, and any unsent data is lost. Any recv() call on the remote side of the 
circuit will fail with WSAECONNRESET. 

If SO JJNGER is set with a non-zero timeout interval, the ciosesocketO call blocks 
until the remaining data has been sent or until the timeout expires. This is called a 
graceful disconnect. Note that if the socket is set to non- blocking and SO_LINGER is 
set to a non- zero timeout, the call to ciosesocketO will fail with an error of 
WS AEWOULDB LOCK. 

If SO_DONTLINGER is set on a stream socket (i.e. the l_onofffie\d of the linger 
structure is zero: see sections 2.4. 4.1.7 and 4.1.21). the ciosesocketO call will return 
immediately. However, any data queued for transmission will be sent if possible before 
the underlying socket is closed. This is also called a graceful disconnect. Note that in 
this case the Windows Sockets implementation may not release the socket and other 
resources for an arbitrary period, which may affect applications which expect to use all 
available sockets. 



Return Value If no error occurs. ciosesocketO returns 0. Otherwise, a value of SO CKET_ ERROR is 
returned, and a specific error code may be retrieved by culling WSAGetLastJErrorO. 

Error Codes WSANOTTNITIALISED A successful WSAStartupO must occur before 

using this API. 

WS AENETDOWN The Windows Sockets implementation has detected 

that the network subsystem has failed. 
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WSAENOTSOCK 

WSAEINPROGRESS 

WSAEINTR 

WSAEWOITLD BLOCK 



The descriptor is not a socket. 

A bloc Jang Windows Sockets call is in progress. 

The (blocking) call was canceled via 
WSACancelBlockingCaliO. 

The socket is marked as nonlocking and 

SO _ LINGER is set to a nonzero timeout value. 



See Also 



acceptQ. socketQ. ioctlsocketO. setsockoptQ. WSAAsyocSelectQ. 
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4.1.4 connectf) 

Description Establish a coanecoon to a peer. 
Jrinclude <winsock.h> 

iot PASCAL FAR connect ( SOCKET j, const struct sockaddr FAR * name, 
int namelen ); 



s A descriptor identifying an unconnected socket. 

name The name of the peer to which the socket is to be connected. 

nameien. The length of the name. 

Remarks This function is used to create a connection to the specified foreign association. The 

parameter s specifies an unconnected datagram or stream socket If the socket is 
unbound, unique values are assigned to the local association by the system, and the 
socket is marked as bound. Note thai if the address Field of the name structure is ail 
zeroes. conoectO will re rum the error WSAEADDRNOTAVAIL. 

For stream sockets (type SOCK_ STREAM), an active connection is initiated to the 
foreign host using name (an address in the name space of the socket). When the socket 
call completes successfully, the socket is ready to send/receive data. 

For a datagram socket (type SOCK_DGRAM). a default destination is sec which will 
be used on subsequent sendQ and recvQ calls. 



Return Value Lf no error occurs. coanectO returns 0. Otherwise, it returns SOCKET_ERROR. and a 
specific error code may be retrieved by calling WSAGetLastErrorO. 

On a blocking socket, the re mm value indicates success or failure of the connection 
attempt. 

On a non-b lor king socket, if the return value is SOCKET_ERROR an application 
should call WS A GetL-astErrorO. If this indicates an error code of 
WS AEWOLTLDB LOCK, then your application can either 

1. Use selectO to determine the completion of the connection request by checking Lf the 
socket is writeahle. or 

2. If your application is using the message -based WSAAsyncSelectO to indicate 
interest in connection events, then your application will receive an FD.CONNECT 
message when the connect operation is complete. 

Error Codes WSANOTTNTTTALISED A successful WSAStartupO must occur before 

using this APL 

WSAENETDOWN The Windows Sockets implementation has detected 

that the network subsystem has (ailed, 

WSAEADDRINUSE The specified address is already in use. 
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See AJso 



The (block-Lag) call was canceled via 
WSACancelBIockiogCailO. 

A blocking Windows Sockets call is in progress. 

The specified address is aot available from the local 
machine. 

Addresses in the specified family cannot be used 
with this socket. 

The attempt to connect was forcefully rejected. 

A destination address is required. 

The name ten argument is incorrect. 

The socket is not already bound to an address. 

The socket is already connected. 

No more file descriptors are available. 

The network can't be reached from this host at this 
time. 

No buffer space is available. The socket cannot be 
connected. 

The descriptor is not a socket. 

Attempt to connect timed out without establishing a 
connection 

The socket is marked as non-blocking and the 
connection cannot be completed immediately. It is 
possible to selectO the socket while it is connecting 
by selectOiog it for writing. 

acceptO. bindQ. getsocknameO. socketQ. selectQ and W SAAsync SelectO- - 



WSAEINTR 

WSAHNPROGRESS 
WSAEADDRNOTAVAIL 

WSAEAFNOSUPPORT 

WSAECONNREFUSED 

WSAEDESTADDREQ 

WSAEFAULT 

WSAHNVAL 

WSAJBSCONN 

WSAEMFILE 

WS AENETUNREA CH 

WSAENOBUFS 

WSAENOTSOCK 
WSAETIMEDOLTT 

WSAEWOULDBLOCK 
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4.1.5 getpeernameO 

Description Get the address of the peer to which a socket is connected, 
^include <wiosock.h> 

lot PASCAL FAR getpeername ( SOCKET s, struct sockaddr FAR • name, iot 
FAR • namelen ); 

s A descriptor identifying a connected socket. 

name The structure which is to receive the name of the peer. 

namelen A pointer to the size of the name s true aire. 



Remarks getpeernameO retrieves the name of the peer connected to the socket s and stores it in 

the struct sockaddr identified by name. It is used on a connected datagram or stream 
socket. 

On return, the namelen argument contains the actual size of the name returned in bytes. 



Return Value If no error occurs. getpeernameO returns 0. Otherwise, a value of SOCKET.ERROR 
is returned, and a specific error code may be retrieved by caJiing WSAGetLastErrorO. 



Error Codes WSANOTINTTIALISED 



WSAENETDOWN 



See AJso 



WSAEFAULT 

WSAEENFROGRESS 

WSAENOTCONN 

WSAENOTSOCK 

bindQ. socketQ. getsoclcnameO- 



A successful WSAStartupO must occur before 
using this API 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The namelen argument is not large enough. 

A blocking Windows Sockets call is in progress: 

The socket is not connected. 

The descriptor is not a socket. 
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4.1.6 getsockname() 

Description Get the local name for a socket. 
#include <winsock.b> 

int PASCAL FAR getsockname ( SOCKET s. struct sock add r FAR ■ name, 
int FAR • namelen ); 



5 A descriptor identifying a bound socket. 

name Receives the address (name) of the socket. 

namelen The size of the name buffer. 

Remarks getsocknameO retrieves the current name for the specified socket descriptor in name. 

It is used on a bound and/or connected socket specified by the s parameter. The local 
association is returned. This call is especially useful when a connectO call has been 
made without doing a bindO first; this call provides the only means by which you can 
determine the local association which has been set by the system. 

On return, the namelen argument contains the actual size of the name returned La bytes. 

If a socket was bound to IN ADD R_ ANY. indicating that any of the host's EP addresses 
should be used for the socket, getsocknameO will not n e c es sarily return Inform a don 
about the host IP address, unless the socket has been connected with conoectO or 
acceptO- A Windows Sockets application must not assume that the IP address will be 
changed from INADDR.ANY unless the socket is connected. This is because for a 
mulri-homed host the EP address that will be used for the socket is unknown unless the 
socket is connected. 

Return Value If no error occurs. getsocknameO returns 0. Otherwise, a value of SO CKET_ERRO R 
is returned, and a specific error code may be retrieved by calling WSAGetLastErrorQ. 



Error Codes WSANOTENTTIAJLISED 

WSAENETDOWN 

WSAEFAULT 
WSAHENPR OGRESS 

WSAENOTSOCK 
WSAHNVAL 

See Also bindQ. socketO. gerpeernameO. 



A successful WSAStartupO must occur before 

n^ing rh\< APL 

The Windows Sockets Implementation has detected 
that the network subsystem has failed. 

The namelen argument is not large enough. 

A blocking Windows Sockets o per ad on is in 
progress. 

Toe descriptor is not a socket. 

The socket has not been bound to an address with 
bindO- 
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4.1.7 getsockoptO 

Description Retrieve a socket option. 

^include <wiosock.h> 

iot PASCAL FAR getsockopt ( SOCKET s, int level, tat opiname, 
cbar FAR • oprval, iot FAR * optlen ); 



s A descriptor identifying a socket. 

level The level at which the option is defined; the only supported levels axe 

SOL.SOCKET and tPPROTO_TCP. 

optname The socket option for which the value is to be retrieved. 

optval A pointer to the buffer in which the value for the requested option is 

to be returned. 

optlen A pointer to the size of the oprval buffer 



Remarks getsockoptO retrieves the current value for a socket option associated with a socket of 

any type, in any state, and stores the result in oprval. Options may exist at multiple 
protocol levels, but they are always present at the uppermost "socket" level. Options 
affect socket operations, such as whether an operation blocks or not, the routing of 
packets, out-of-band data transfer, etc. 

The value associated with the selected option is returned in the buffer optval. The 
integer pointed to by optlen should originally contain the size of this buffer; on return, 
it will be set to the size of the value returned. For SO_LINGER. this will be the size of 
a struct Linger; for all other options it will be the size of an integer. 

If the option was never set with setsockoptQ. then getsockoptO returns the default 
value for the option. 

The following options are supported for getsockoptO- The Typ e identifies the type of 
data addressed by optval. The TCP_NODEL A Y option uses level IPPROTOJTCP; all 
other options use level S0L_SOCKET. 



Value 


Type 


Meaning 


SO.ACCEFTCOrVN 


BOOL 


Socket is listenOing. 


SO.BROADCAST 


BOOL 


Socket is configured for the transmission of 






broadcast messages. 


SO.DEBUG 


BOOL 


Debugging is enabled. 


SO_DO NTLINGER 


BOOL 


if true, the SO.LINGER option is disabled. 


SO_DONTROUTE 


BOOL 


Routing is disabled. 


SO.ERROR 


int 


Retrieve error status and clear. 


SO.KEEP ALIVE 


BOOL 


Keepaiives are being sent. 


SO.LINGER 


struct linger 


Returns the current linger options. 




FAR * 




SO.OOB INLINE 


BOOL 


Out-of-band data is being received in the normal 






data scream. 


SO.RCVBUF 


int 


Buffer size for receives 
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SO.REUSEADDR BOOL 

SO.SNDBUF int 

SO.TYPE Int 

TCP NODELAY BOOL 



The socket may be bound to an address which is 
already in use. 
Buffer size for sends 

The type of the socket (e.g. SOCK.STREAM). 
Disables the Nagie algorithm for send coalescing. 



10 



BSD options not supported for getsockoptO are: 



75 



Value Tvr>e 

SO.RCVLOWAT int 

SO_RCVTTMEO int 

SO_SNDLOWAT int 

SO_SNDTIMEO int 
IP.OPTTONS 

TO?_MAXSEG int 



Receive low water mark 

Receive timeout 

Send low water mark 

Send timeout 

Get options in EP header. 

Get TCP maximum segment size. 



20 



Calling getsockoptO with an unsupported option will result in an error code of 
WSAJENOFROTOOPT being returned from WSAGetLastErrorO. 



25 



30 



35 



40 



45 



Return Value tf no error occurs. getsockoptO returns 0. Otherwise, a value of SO CXET_ ERROR is 
returned, and a specific error code may be retrieved by calling WSAGetLastErrorO- 



Error Codes 



WSANOTINTTTALLSED 
WSAENETDOWN 

WSAEFAULT 
WSAONFROGRESS 

WS AENOPROTOOPT 



WSAENOTSOOC 



A successful WSAStartupO must occur before 
n^ing this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The optlen argument was invalid. 

A blocking Windows Sockets operation is in 
progress. 

The option is unknown or unsupported. In 
particular, SO_BROADCAST is not supported on 
sockets of type SOCK.STREAM, while 
SO_ACCEPTCONN. SO.DONTLINGER. 
SO.KEEP ALIVE. SO_LINGER and 
SO.OOB INLINE are not supported on sockets of 
type SOCK_DGRAM. 

The descriptor is not a socket. 
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See AJSO setsockoptQ. WSAAsyncSelectQ. socketQ. 
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4.1.8 htonl() 

Description Coaven a u_loog from host to oecwork byte order, 
^include <wiosock.h> 

ujong PASCAL FAR htoal ( u Joag hostlong ); 

hostlong A 32-bit number in host byte order. 

Remarks This routine cakes a 32-bit number in host byte order and returns a 32-bit number in 

network byte order. 

Return Value htoolO returns the value in network byte order. 
See Also htoasO. ntohlQ. ntohsO. 



htons 32 



4.1.9 htons() 

Description Coavert a u_short from host to network byte order, 
^include <winsock.h> 

u_short PASCAL FAR htons ( u_snort hostshon ); 

hostshort A 16-bit number in host byte order. 

Remarks This routine takes a 16-bit number in host byte order and returns a 16-bit number in 

network byte order. 

Return Value htonsO reruras the vaiue in network byte order. 
See AJso htoolO. ntohJO. ntohsQ. 
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4.1.10 Inet_addr() 

Description Convert a string containing a dotted address into an io_addr. 
# include <winsock.h> 

unsigned long PASCAL FAR inet.addr ( coast char FAR • cp ); 

cp A character string representing a number expressed in the Internet 

standard V notation. 

Remarks This function interprets the character string specified by the cp parameter. This string 

represents a numeric Internet address expressed in the Internet standard "." notation. 
The value returned is a number suitable for use as an Internet address. All Internet 
addresses are returned in network order Cbytes ordered from left to right). 

Interact Addresses 

Values specified using the notation take one of the following forms: 
a.b.c.d a.b.c a.b a 

When four parts are specified, each is interpreted as a byte of data and assigned, from 
left to right, to the four bytes of an Internet address. Note that when an Internet address 
is viewed as a 32- bit integer quantity on the Intel architecture, the bytes referred to 
above appear as "d.c.b.a". That is. the bytes on an Intel processor are ordered from 
right to left. 

Note: The following notations are only used by Berkeley, and nowhere else on the 
Internet. In the interests of compatibility with their software, they are supported as 
specified. 

When a three part address is specified, the last part is interpreted as a 16-bit quantity 
and placed in Lhe right most two bytes of the network address. This makes the three 
part address format convenient for specifying Class B network addresses as 
"l28-netJiost\ 

When a two part address is specified, the last pan is interpreted as a 24-bit quantity and 
placed in the right most three bytes of the network address. This makes the two part 
address format convenient for specifying Qass A network Addresses as "net-host". 

When only one pan is given, the value is stored directly in the network address without 
any byte rearrangement. 

Return Value If no error occurs, inet.addrO returns an unsigned long containing a suitable binary 
representation of the Internet address given. If the passed- Ln string does not contain a 
legitimate Internet address, for example if a portion of an "a.b.c.d" address exceeds 255. 
inet.addrO returns the value INADDR^NONE. 

See AJso inet.ntoaO 
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4.1.11 Inet_ntoa() 

Description Convert a network address Into a string in dotted format, 
^include <winsock.b> 

char FAR • PASCAL FAR inet.ntoa ( struct io_addr in ); 



in 



A structure which represents an Internet host address. 



Remarks This rune don takes an Internet address structure specified by the in parameter. It 

returns an ASCII string representing the address in notation as "a.b.c.d". Note that 
the string returned by inet_QtoaO resides in memory which is allocated by the 
Windows Sockets implementation. The application should not make any assumptions 
about the way in which the memory is allocated. The data is guaranteed to be valid 
until the next Windows Sockets API call within die same thread, but no longer. 



Return Value 



See Also 



If no error occurs. inet_ntoaQ returns a char pointer to a static buffer containing the 
text address in standard V notation. Otherwise, it returns NULL. The data should be 
copied before another Windows Sockets call is made. 

inet_addrQ. 
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4.1.12 Ioct!socket() 

Description Control die mode of a socket. 



^include <winsock.h> 

int PASCAL FAR ioctlsocket ( SOCKET s t long cmd. ujong FAR • argp ); 



cmd 



argp 



A descriptor identifying a socket. 

The command to perform on the socket s. 

A pointer to a parameter for cmd. 



Remarks This routine may be used on any socket in any state. It is used to get or retrieve 

operating parameters associated with the socket, independent of the protocol aad 
communications subsystem. The following commands are supported: 



Cpmrnnnri 



Semantics, 



FIONBIO Enable or disable noo-blocking mode an the socket s. argp points at 

an unsigned long, which Ls non-zero if non-blocking mode is to be 
enabled and zero if it is to be disabled. When a socket is created, it 
operates in blocking mode (i.e. non- blocking mode is disabled). This 
is consistent with BSD sockets. 

The WSAAsyncSelectO routine automatically sets a socket to 
nonblocking mode. If WSAAsyncSelectO has been issued on a 
socket, then any attempt to use ioctlsocketO to set the socket back to 
blocking mode will fail with WSAEQMVAL. To set the socket back to 
blocking mode, an application must first disable WSAAsyncSelectO 
by calling WSAAsyncSelectO with the lEvem parameter equal to 0. 

FIONREAD Determine the amount of data which can be read atomic ally from 
socket s. argp points at an unsigned long in which ioctlsocketO 
stores the result. If s is of type SOCK.STREAM. FIONREAD returns 
the total amount of data which may be read in a single recvO: this is 
normally the same as the total amount of data queued on the socket 
If j is of type SOCK JXjRAM. FIONREAD returns the size of the 
first datagram queued on the socket 

S IOCATMARK Determine whether or not all out -of- band data has been read. This 
applies only to a socket of type S OCK_STR£AM which has been 
configured for in-line reception of any out-of-band data 
(SO^OOB INLINE). If no out-of-band data is waiting to be read, the 
operation returns TRUE. Otherwise it returns FALSE, and the next 
recvO or recvfromO performed on the socket will retrieve some or all 
of the data preceding the "mark"; the application should use the 
S IOCATMARK operation to determine whether any remains. If there 
is any normal data preceding the "urgent" 1 (out of band) data, it will be 
received in order. (Note that a recvO or recvfromO will never mix 
out-of-band and normal data in the same call.) argp points at a 
BOOL in which ioctlsocketO stores the result. 
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Compatibility This function is a subset of ioctJO as used In Berkeley sockets. In particular, there is no 
command which is equivalent to FIOASYNC. while S10CATMARK is the only socket- 
level command which is supported. 



Return Value Upon successful completion, the ioctlsocketO returns 0. Otherwise, a value of 

SOCKET. ERROR is returned, and a specific error code may be retrieved by calling 
WSAGetLastErrorO. 



Error Codes 



WS ANOTTNTTIALISED 

WSAENETDOWN 

WSAETNVAL 

WSAEINPROGRESS 
WSAENOTSOCK 



A successful WSAStartupO must occur before 

tiding rhi< API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

cmd is not a valid command, or argp is not an 
acceptable parameter for cmd. or the command is 
not applicable to the type of socket supplied 

A blocking Windows Sockets operation is in 
progress. 

The descriptor s is not a socket. 



See Also socketQ. setsockoptQ. getsockoptQ* WSAAsyncSelectO- 



51 



EP 0 770 958 A1 



listen 37 



4.1.13 llstenO 

Description Establish a socket to listen for incoming connecLioa. 
^include <winsock.h> 

int PASCAL FAR listen ( SOCKET s, int backlog ); 

s A descriptor identifying a bound, unconnected socket. 

backlog The maximum length to which the queue of pending connections may 

grow. 

Remarks To accept connections, a socket is first created with socketO. a bacldog for incoming 

connections is specified with listenO. and then the connections are accepted with 
acceptO. listenO applies only to sockets that support connections, i.e. those of type 
SO CK_ STREAM. The socket s is put into "passive" mode where incoming connections 
are acknowledged and queued pending acceptance by the process. 

This function is typically used by servers that could have more than one connection 
request at a time: Lf a connection request arrives with the queue full, the client will 
receive an error with an indication of WSA£CONNRthlJSED. 

listen 0 attempts to continue to function rationally when there are no available 
descriptors. It will accept connections until the queue is emptied. If descriptors 
become available, a latex call to listen 0 or acceptQ will re-fill the queue to the current 
or most recent "backlog", if possible, and resume listening for incoming connections. 

Compatibility backlog is currently limited (silently) to 5. As in 4.3BSD. illegal values (less than 1 or 
greater than 5) are replaced by the nearest legal value. 

Return Vaiue If no error occurs. listenO returns 0. Otherwise, a value of SOCKET_ERROR is 

returned, and a specific error code may be retrieved by calli n g WSAGetLastErrorQ 



Error Codes 



WSANOTTNTTIALISED 

WSAENETDOWN 

WSAEADDRINUSE 

WS ASNFROGRES S 

WSAEINVAL 

WSAE1SCONN 

WSAEMFILE 

WSAENOBUFS 



A successful WSAStartupO must occur before 

lining thig API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

An attempt has been made to listen 0 on an address 
in use. 

A blocking Windows Sockets operation is in 
progress. 

The socket has not been bound with bLndO or is 
already connected. 

The socket is already connected. 

No more file descriptors are available. 

No buffer space is available. 
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See Also 



WSAEN'OTSOCK 
WSAEOPNOTSUPP 

accept(), coaaectO. socketQ. 



The descriptor is aot a socket. 

The referenced socket is aot of a type that supports 
the UsteoQ operation. 



ntohl 39 



4.1.14 ntohl() 

Description Convert a ujoag from aecwork to host byte order, 
^include <winsock.h> 

u_long PASCAL FAR ntohl ( ujoag netlong )• 



net long 



A 32-bit number La network byte order. 



Remarks This routine takes a 32-bit number in network byte order and returns a 32-bit number in 

host byte order. 



Return Value atohIO returns the value in host byte order. 
See AJso htoalQ. htoasO. ntohsO- 
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4.1.15 ntohs() 

Description Convert a u^sbort from aerworlc co host byte order, 
^include <winsock.h> 

u_short PASCAL FAR atohs ( u_short netshon ); 

netshort A 16-bic aumber in network byte order- 

Remarks This routine takes a 1 6-bit aumber in aerworic byte order and returns a i 6-bit aumber La 

host byte order. 

Return Value atohsO rerurns the value Ln host byte order. 
See Also htoalQ. htoasQ. atobiQ. 
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4.1.16 recv() 

Description Receive data from a socket. 

^include <wiasock.b> 

int PASCAL FAR recv ( SOCKET char FAR • but, int Un. int fla%s ): 



r A descripLor idea dfy Lag a connected socket. 

buf A buffer for the Lacomiag data. 

ten The leagth of buf. 

flags Specifies the way La which the coil is made. 



Remarks This function is used oa connected da La grain or scream sockets specified by the s 

parameter and is used to read incoming data. 

For sockets of rype SOCK_S"TREAM. as much information as is currendy available up 
to the sue of the buffer supplied is returned. If the socket has beea configured for in- 
line reception of out -of -band data (socket op don SO_OOB INLINE) and out -of -band 
data is unread, only out-of-band data will be returned. The application may use the 
ioctisocketO SIOCATMARK to determine whether any more out-of-band data remains 
to be read. 

For datagram sockets, data is extracted from the first enqueued datagram, up to the size 
of the buffer supplied. If the datagram is larger than the buffer supplied, the buffer is 
filled with the first part of the datagram, the excess data is lost, and recvO re rums the 
error WSAEMSGSEE. 

If no uicorning data is available at the socket, the recvO call waits for data to arrive 
unless the socket is non-blocking. In this case a value of SOCKET.ERROR is returned 
with the error code set to WSAEWOLTLDBLOOK. The selectO or YVSAAsyncSelectO 
calls may be used to determine when more data arrives. 

If the socket is of rype SOCK_STR£AM and the remote side has shut down the 
connection gracefully, a recvO will complete immediately with 0 bytes received. If the 
connection has been reset, a recvQ will fail with the error WSAECONNRESET. 

Flags may be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. Thai is. the semantics of this function are 
deter mine d by the socket options and the flags parameter. The I arte r is constructed by 
or-ing any of the following values: 

V ^"e Vanning 

MS G_ PEEK Peek at the incoming data. The data is copied into the buffer but is 
not removed from the input queue. 

MSG.OOB Process out-of-band data (See «ctioa 2.2.3 for a discussion of this 
topic.) 
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Return Value If no error occurs. recvQ rerurns the number or bytes received, if the connection has 
been closed, it returns 0. Otherwise, a value of SOCK£T_ERROR is returned, and a 
specific error code may be retrieved by calling WSAGetLastErrorO. 

ErTor Codes VVSANOTINTTXALISED A successful VVSASurtupO must occur before 

usmg this .API. 

The Windows Sockets Implementation his detected 
that the nerwork subsystem has failed. 

The socket is not connected. 

The (blocking) call was canceled via 
WSACancelBlockingCaliO. 

A blocking Windows Sockets operation is in 
progress. 

The descriptor is not a socket. 

\LSG_OOB was specified, but the socket is not of 
type SOCX.STRJEAM. 

The socket has been shutdown; it is not possible to 
recvO on a socket after shutdownO has been 
invoked with how set to 0 or 2. 

WSAEWOUIX> BLOCK Toe socket is marked as non-blccking and the 

receive operation would block. 

WS AEMSGSIZE The datagram was too large to fit into the specified 

buffer anH was truncated. 

WSAHNVAL The socket has not been bound with bindO. 

WS AJECONN ABORTED The virtual circuit was aborted due to timeout or 

other failure. 

W S AE C O HNKES ET The virtual circuit was reset by the remote side. 

See Also recvfromO. I'tfldQ. .recvQ, seodQ. selectQ. VVSAAsyncSelectQ. socketQ 



WS.AENETDOWN 

WS.AZNOTCONN 
WSAEINTR 

WS.AEENPROGR-ESS 

WSAENOTSOCK 
WSAEOPNOTSUFP 

WSAESHLTDOWN 
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4.1.17 recvfrom() 

Description Receive 3 data-jam md store the source address, 
-include <win$ock.h> 

■ nt PASCAL FAR recvfrom ( SOCKET s. chur FAR • ouf int !en. int fldqs, 
struct sockaddr FAR m from, int FAR • fro mien ); 



s A descriptor identifying a bound socket. 

buf A buffer for the incoming data. 

Un The length of buf 

flags Specifies the way in which the call is made. 

from An optional pointer to a buffer which will hold the source address 
upon re rum. 

from ten An optional pointer to the size of [he from buffer. 



Remarks This function is used to read incoming data on a (possibly connected) socket and 

cap aire the address from which the data was sent. 

For sockets of type SOCK_STREAM. as much. information as is currendy available up 
to the size of the buffer supplied is re aimed. If the socket has been configured for in- 
line reception of out-of-band data (socket option SO.OOBONUNE) and out-of-band 
data is unread, only out-of-band data will be returned. The application may use the 
ioctlsocketO SIOCATMARK :o determine whether any more out-of-band data remains 
to be read. The from and from Un parameters are ignored for SOCK_STR£AM sockets. 

For datagram sockets, data is exiracted from the first enqueued datagram, up to the size 
of the buffer supplied. If the datagram is larger than the buffer supplied, the buffer is 
filled with the first pan of the message, the excess data is lost, and recvfromO re aims 
the error code WSAEMSGSEZE. 

If from is aon-zero. and the socket is of cype SOCK.DGRAM. the network address of 
the peer which sent the data is copied to the corresponding struct soclcaddr. The value 
pointed to by from len is initialized to the size of this structure, and is modified on re mm 
to indicate the actual size of the address stored there. 

If ao incoming data is available at the socket, the recvfromO call waits for data to 
arrive uniess die socket is non- blocking. In this case a value of SOCKET_ER_ROR is 
rerurned with the error code set to WSAEW'O LTLD BLOCK. The selectO or 
WSAAsyncSelectO calls may be used to determine when more data arrives. 

If the socket is of type SOCK_STR£AM and the remote side has shut down the 
connection gracefully, a recvfromO will complete immediately with 0 bytes received. 
If the connecQcm has been reset recvO will faii with the error W$A£COiVN*R£SET. 

Flags may be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. Thai is. the semantics of this function are 
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10 



determined by ±c socket opcioos ind ihe parameter. Toe latter is conscuc-ed by 
or- Lag any of ±e following values: 



v ilue 



Mrrnrs 



MSG_PEEK Peek at ±e incoming data. Tae data is copied into ±e buffer biu is 
cot removed from uie input queue. 

MSG_OOB Process out-of-band data (See sectioa 2.2.3 for a discussion ot" this 
tooic.) 



is 



20 



25 



30 



35 



40 



45 



50 



Return Value if ao error occurs, recvfromO returns the number of bytes received. If the coanecdoa 
has been closed, it renirns 0. Otherwise, a vaiue of SOCK£T_ ERROR is returned, and 
a specific error code ciay be retrieved by calling WSAGetLastErTorQ. 



Error Codes 



WS ANOTTNTTTAJL IS ED 

WSAZNEIDOWN 

WSAHFAULT 

WSAEEsTR 

WSAEINPROGRESS 

WSAEjOTVAL 
WSAJENOTCONN 

WSAEN'OTSOCK 
WSAEOPNOTSUFP 

WSAESHbTDOWN 

WS AJEWOULDB LOCK 

WSAJEMSGSIZE 

WS AECO NN.-VB ORTED 



A successful WSAStartupO must occur before 

n^ing f hk .API. 

The Windows Sockets im pie men can on has detected 
that the network subsystem has failed. 

The fro mien argument was invalid: the from buffer 
was too small to accommodate the peer address. 

The (blocking) call was canceled via 
WSACajQcelBlockingCallO. 

A blocking Windows Sockets ope ran on is in 
progress. 

The socket has not been bound with bindO- 

The socket is not connected (S OCK _ STREAM 
only). 

The descriptor is not a socket. 

\lSG_OOB was specified, but the socket is aot of 
type SOCK.STREAM. 

The socket has been shutdown; it is not possible to 
recvfromO on a socket after shut down 0 has been 
invoked with how set to 0 or 2. 

The socket is marked as non-blocking and the 
recvfromO operadon would block. 

The datagram was too large to fit into the specified 
buffer and was mine axed. 

The virtual circuit was aborted due to omeoui or 
other failure. 
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5 

WS A£CON~N~RESET Toe virruai circuit * reset by the remote side. 

w See Also recvQ. sendO. socketQ. VV'SAAsyncSelectQ. 

15 
20 
25 
30 
35 
40 
45 
50 
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4.1.18 selectQ 

Description Deiernu^e the starus of one or more socJtecs. waiting If necessary, 
-include <win*»otW.h> 

int PASCAL FAR select ( iot n/ds. fd.set FAR • readfds. fd.set FAR • wntefds. 
fd_set FAR • excepqds. const struct timevaJ FAR • :imet;ut ); 



nfds This argument is ignored and included ooiy tor the sake of 

compatibility. 

readfds An optional pointer to a set of sockets to be checked for readability. 

wiufds .An optional pointer to a set of sockets to be checked for vritability 

excepifds .An optional pointer to a sec of sockets to be checked for errors. 

timeout The maximum time for selectQ to wait, or NULL for blocking 

operation. 



Remarks This function is used to determine the status of one or more sockets. For each socket. 

the caller may request information on read, write or error status. The set of sockets for 
which a given status is requested is indicated by an fd_set structure. Upon return, the 
structure is updated to reflect the subset of these sockets which meet the specified 
condition, and selectQ re rums the number of sockets inhering the conditions. A set of 
macros is provided for manipulating an fd_set. These macros are compatible with those 
used in the Berkeley software, but the underlying representation is completely different. 

The parameter readfds identifies those sockets which are to be checked for readability. 
If the socket is currently listenOuiS. it will be marked as readable if an incoming 
connection request has bee a received, so that an acceptO is guaranteed to complete 
without blocking. For other sockets, readability means that queued data is available for 
reading or. for sockets of type SOCX_STREAM. that the virtual socket corresponding 
co the socket has been closed, so that a recvQ or recvfromO is guaranteed to complete 
without blocking. If the virtual circuit was closed gracefully, then a recvO will return 
Immediately with 0 bytes read: if the virtual circuit was reset, then a recvQ will 
complete immediately with the error code WSA£CONNR£SET. The presence of out- 
of-band data will be checked if the socket option SO_OOB INLINE has been enabled 
(see setsockopeO). 

The parameter write fas identifies those sockets which are to be checked for wri Lability. 
If a socket is connectOing (non- blocking), writ-ability means that the connection 
establishment successfully completed. If the socket is not in the process of 
conaectOtng. wriubility means that a sea dQ or sendtoO will complete without 
blocking. [It is not specified how long this guarantee can be assumed to be valid, 
particularly in a multithreaded environment.) 

The parameter exceprfds identifies those sockets which are to be checked for the 
presence of out-of-bacd data or any exceptional error conditions. Note that out-of-band 
data will only be reported in this way if the option SO_OOB INLINE is FALSE. For 3 
SOCK.STREAM. the breaking of the connection by the peer or due to KEEP ALIVE 
failure will be indicated as an exception. This specification does not define which other 
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10 



15 



errors w. • I be included. If a socket is connectO^S (con-blockings failure of the 
connect attempt is indicated in txcepefds 

Any or" recJ/Js. wrtte/ds. or exctpcfas may be given as NULL if qo descriptors are of 
interest. 

Four macros are defined in the header File winsock.h ;or manipulating the descriptor 
sets. The variable FD_SETSrZ_E determines the maximum number of descriptors La a 
set. (The default value of FD_ SET SIZE is 64. which may be modified by defining 
FD_SETSIZE to another value before ; finclucUng winsock.h.) Internally, an fd_set ls 
represented as an array of SOCKETs; me last valid en07 is followed by an element set 
to f>Tv\ALED_SOCKET. The macros are: 



20 



FD_CLR(j, m set) 
FO_ISSET(j, m set) 
FD_SET(5, •set) 
FD_ZZRO(*set) 



Removes the descriptor s from set. 

Nonzero if s is a member of the set. zero otherwise. 

Adds descriptor s to set. 

Initializes the set to the NULL set. 



25 



30 



Return Value 



The parameter timeout controls how long the selectO may Lake to complete. If timeout 
is a null pointer. selectO W i-U block m definitely until at least one descriptor meets the 
specified criteria. Otherwise, timeout points to a struct dmeval which specifies the 
maximum time that selectO should wait before returning. If the rimeval is initialized to 
{0. 0). selectO will return immediately; this is used to "poll" the state of the selected 
sockets. If this is the case, then the selectO call is considered nonblocldng and the 
standard assumptions for nonblocldng calls apply. For example, the blocking hook 
must not be called, and the Windows Sockets implementation must not yield. 

selectO returns the total number of descriptors which are ready and contained in the 
fd_set structures. 0 if the time limit expired, or 50CKET_ERROR if an error occurred. 
If the return value is SOCKET. ERROR. WSAGetLast£rrorO may be used to retrieve 
a specific error code. 



40 



Error Codes WSANOTTNTTLALISED 



WSAENEXDOWN 



45 



WSAEQWAL 



WSAETNTR 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets im piemen Lad on has detected 
that the network subsystem has failed. 

The timeout value is not valid. 

The (blocking) call was canceled via 
WSACancelBlockiagCaUO. 



50 



A blocking Windows Sockets operation is in 
progress. 



See Also 



WSAEINFROGRESS 
WSAEN'OTSOOC 
WSAAsyncSelectO. acceptO. coooectQ. recvQ. recvfromO. sendQ 



One of the descriptor sets contains an entry which is 
no* a socket. 
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4.1.19 send() 

Description Send data on a connected socket, 
^include <wins*>cic.h> 

int P ASCAL FAR s*nd t SOCKET s. const char FAR • huf. int Un % ml /7j?y J; 



j A descriptor identifying 3 connected socket. 

6^/ A buffer coaraining me data to be cransmitied. 

/en The length of the dau in buf. 

flags Specifies the way In which the call is made. 



Remarks sendO is used on connected datagram or stream sockets and is used to write outgoing 

dau on a socket. For datagram sockets, care must be oaken not to exceed the maximum 
EP packet size of the underlying subnets, which is given by the iMaxUdpDg element in 
the WSADaia structure returned by WSAStartupO- If the dau is too long to pass 
atomic ally through the underlying protocol the error WSAEMSGSIZE is returned, and 
. no data is transmitted. 

Note that the successful completion of a sendO does aot indicate that the data was 
successfully delivered. 

If no buffer space is available within the transport system to hold the data to be 
transmitted. sendO will block unless the socket has been placed in a non-blocking I/O 
mode. On non-biorlring SOCK.STRJEAM sockets, the number of bytes written may be 
between 1 and the requested length, depending on buffer availability on both the local 
and foreign hosts. The selectG call may be used to determine when it is possible to 
send more data. 

Flags may be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. Thar is, the semantics of this function are 
determined by the socket options and the flags parameter. The latter is constructed by 
or- Lag any of the following values: 

Value Vfp.gniny 

MSG_DO NTROUTE 

Specifies that the dau should not be subject to routing. A Windows 
Sockets supplier may choose 10 ignore this flag: see also the 
discussion of the SO_DONTRO0TE option in section 2.4. 

MSG_OOB Send out -of- band dau (SOCK_STR£AM only: see also section 2.2.3) 

Return Value If no error occurs. seodO returns the total number of characters sent. (Note that this 
may be less than the number indicated by ten.) Othera/Lse. a value of 
SOCKET_ERROR is returned, and a specific error code may be retrieved by calling 
WSAGet£ast£rrorQ. 
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Error Codes WSANOTINTTIAJLISED 
WSAENETDOWN 

'vVSAEACCES 

WSaEPnTR 

WSAEINPROGR£SS 

WSAEFAULT 

W'SAENFTKJESET 

WSAENOBUFS 

WSAENOTCONN 
WSAENOTSOCK 
WSAEOPNOTSUPP 

WS AES hltdo wn 

WS AEWO ULD B LOCK 
WSAEMSGSIZE 

WSAEENVAL 
WSAECONN ABORTED 

W S AECO iVfNRES ET 



A Tuccessiui WSAStarnipO must occur before, 
using this .API. 

The Windows Sockets implementation has detecied 
chat the ae:work suosys;em has failed. 

The requested address :s a broadcast address, buc the 
appropriate flag was cot set. 

The (blocking) call was canceled via 
WSACancelBlockiagCallO. 

A blocking Windows Sockets operatioa is in 
progress. 

The buf argument is doc in a valid part of the user 
address space. 

The connection must be reset because the Windows 
Sockets implementation dropped it. 

The Windows Sockets Implementation reports a 
buffer deadlock. 

The socket is not connected. 

The descriptor is not a socket. 

MSG.OOB was specified, but the socket is not of 
type S~OCK_STREAM. 

The socket has been shutdown; it is not possible to 
seodO on a socket after shutdownQ has been 
invoked with how set to I or 2. 

The socket is marked as non-blocking and the 
requested operation would block. 

The socket is of type SOQC_DGRAM. and the 
datagram is larger than the maximum supported by 
the Windows Sockets implementation. 

The socket has not been bound with bindO- 

The virtual circuit was aborted due to timeout or 
other failure. 

The virtual circuit was reset by the remote side. 



See Also 



recvf). recvfromQ. socketQ. seodtoO. WSASUrmpO- 
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4.1.20 sendto() 

Description Seac dau to j specific cesunauaa. 
^include <wiasock.h> 

int PASCAL FAR send to ( SOCKET r. const char FAR • bu/\ int ien, int fla%s. 
ct>nst struct sockaddr FAR • to, int :uien ); 



s 


A descriptor identifying a socket. 


buf 


A buffer containing the data to be □rausmitted. 


ten 


The length of the dau La buf. 


flags 


Specifies the way in which the call is made. 


to 


.\n optional pointer to the address of die target socket. 


to ten 


The size of the address in to. 



Remarks seodtoO is used on datagram or stream sockets and is used to write outgoing data on a 

socket. For datagram sockets, care must be taken not to exceed die maximum IP packet 
size of the underlying subnets, which is given by the tMaxUdpDg element in the 
WSAData s true aire rerurned by WSAStartupO- If the data is too long to pass 
atomicaiiy through the underlying protocol the error WSAEMSGSEE is returned, and 
no dau is transmitted. 

Note that the successful completion of a sendtoO does not indicate that the data was 
successfully delivered. 

sendtoO is normally used on a SOCK.DGRAM socket to send a datagram to a specific 
peer socket identified by me to parameter. On a S OCX _ STREAM socket, the to and 
tolen parameters are ignored; in this case the sendtoO is equivalent to sendO- 

To send a broadcast (on a SOCKJDGRAM only), the address in the to parameter should 
be constructed using the special IP address INA£>DR_BROADCAST (defined in 
winsock.h) together with the intended port number. It is generally inadvisable for a 
broadcast datagram to exceed the size at which fragmentation may occur, which implies 
that the data portion of the datagram (excluding headers) should not exceed 512 bytes. 

If no buffer space is available within the transport system to hold the data to be 
tr ansmi tted. sendtoO will block unless the socket has been placed in a noo- blocking I/O 
mode. On aon-blocJdng SOCK_STO£AM sockecs. the number of bytes wrinen may be 
between 1 and the requested length, depending on buffer availability on both the local 
and foreign hosts. The selectf) call may be used to determine when it is possible to 
send more data. 

Flags a ay be used to influence the behavior of the function invocation beyond the 
opaons specified for the associated socket. That is. the semantics of this function are 
dete rm i ne d by the socket options and the flags parameter. The latter is constructed by 
or-ing any of the following values: 
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v -iiug Meaning 

5 MSG _ DO NTROITE 

Specifies that the data should 201 be subject to rouung. A Windows 
Sockets supplier may choose to ignore this flag: see also che 
discussion of che SO_DONTROLTE option Ln section . 

w MSGJDOB Sead out-of-baad data (SOCK_STRE-\M ooiy: see also section } 



Return Value if zo error occurs. sendtoO returns the total number of characters sent. (Note that this 
may be less than the number indicated by len.) Otherwise, a value of 
SO CrC£T_ ERROR is returned, and a specific error code may be retrieved by calling 
WSACctLastEnrorO. 

Error Codes W S ANOTINTTLAJL I S ED A successful WSAStartupO must occur before 

using this API. 

The Windows Sockets im piemen tan on has defected 
that the oerwork subsystem has failed. 



WSAENETDOWN 



WS AEACCES 

25 

WSAEINTR 
WSAEEN7R0GRESS 

30 

WSAEFAULT 



WS AENETRES et 
WSAENOBUFS 

40 

WSAENOTCONTSf 
WSAEN-OTSOCK 

45 

WSAEOPNOTSUPP 
WSAESHLTDOWN 

50 



The requested address is a broadcast address, but the 
appropriaie flag was not set. 

The (blocking) call was canceled via 
WS A CancelB I oc IcingC aU 0 . 

A blocking Windows Sockets operation Ls m 
progress. 

The buf or to parameters are not pan of the user 
address space, or the to argument is too small (less 
than the sizeof a s cruet socicaddr). 

The connection must be reset because the Windows 
Sockets implementation dropped it. 

The Windows Sockets implementation reports a 
buffer deadlock. 

The socket is not connected (SOCK .STREAM 
only). 

The descriptor is not a socket. 

MSG_OOB was specified, but the socket is not of 
rype SOCK . STREAM. 

The socket has been shutdown; it is not possible to 
sendtoO on a socket after shutdown!) has been 
invoked with how set to I or 2. 



WS AEWOt/LD B LOCK The socket is marked as non-blocking and the 

requested operation would block. 
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WSAEMSGSEZE 

io VVSAECONNABORTED 

WSAECONNRESET 
is WSAE\DDRNOTAV.\JDL 

WSAE.-VFNOSUPPORT 

20 

WS AED EST AD D RREQ 
WS AEN'ETL'NRE-A CH 

25 

See AJ so recvO. recvfromO. socketO. 

30 
35 
40 
45 
SO 
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Tae socket is of type SOCK.DGRAM. and the 
datagram is larger than die maximum supported by 
the Windows Sockets implementation. 

The virtual circuit was aborted due to timeout or 
other failure. 

The virtual circuit was reset by the remote side. 

The specified address is not available from the local 
machine. 

Addresses in the specified family cannot be used 
with this socket. 

A destination address is required. 

The network can't be reached from this host at this 
time. 

d0. WSAStartupQ. 
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4.1.21 setsockopt() 
Description S;i a sccket opdoo. 

"include <winsock.h> 

int PASCAL FAR strtsockopt ( SOCKET s. int level, int opmame. 
const char FAR • ocr.-ai. int opt ten )\ 



s A descriptor identifying 3 socket. 

ievel The level at which die option is defined; the ooJy supported levels are 

SOL.SOCKET and IPPROTO_TCP. 

optname The socket option for which the value is to be set. 

oprval A pointer to the buffer in which the value for the requested option is 

supplied. 

optlen The size of the oprsal buffer. 

Remarks setsockoptQ sets the current value for a socket option associated with a socket of any 

type. La any state. Although options may exist at multiple protocol levels, this 
specification only defines options that exist at the uppermost "socket" level. Options 
affect socket operations, such as whether expedited data is received in the normal data 
scream, whether broadcast messages may be sent on the socket, etc. 

There are two types of socket options: Boolean options that enable or disable a feature 
or behavior, and options which require an integer value or structure. To enable a 
Boolean option, oprval points to a nonzero integer. To disable the optioa oprval points 
to an integer equal to zero, optlen should be equal to sizeof(int) for Boolean options. 
For other options, oprval points to the an integer or structure that contains the desired 
value for the option, and op (ten is the length of the integer or structure. 

SO_ LINGER controls the action taken when unseat data is queued on a socket and a 
closesocketO is performed. See closesocketO for a description of the way in which the 
SO_LINGER settings affect the semantics of closesocketO. The application sets the 
desired behavior by creating a struct linger (pointed to by the oprval argument) with the 
following elements: 

a:rucc 1 ir.ge c ( 

i.-i I_ono££; 
in: 1_1 inger ; 

} 

To en-able SO_L£NCTER. the application should set / onoff to a non-zero value, set 
ijinger to 0 or the desired timeout (in seconds), and call seLsockoptO To enable 
SO_DONTLINGER (i.e. disable S0_ LINGER) l_onoff should be set to zero and 
setsockoptO should be called. 

By default, a socket may not be bound (see bindO) to a local address which is already 
in use. On occasions, however, it may be desirable to "re-use" an address in this way. 
Since every connection is uniquely identified by the combination of local and remote 
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addresses, there is qo problem wild having two sockets bound to che same local address 
as loDg as the remote addresses ore different. To inform the Windows Sockets 
unplemeaiauoa that a bind(j on a socket should not be disallowed because the desired 
address Ls already in use by another socket, the application should set the 
SO_R£USEADDR socket option for the socket before issuing the bindO- Note that the 
option is interpreted only at the time of the bind(): it is therefore unnecessary (hut 
harmless) to set the opdoa oq a socke: which is not to be bound to an existing address, 
and setting or resetting the option after the btndl) has no effect oq this or any other 
socket. 

An application may request that the Windows Sockets implementation enable the use of 
"keep-alive" packets on TCP connections by turning on the SO_rCEEP ALIVE socket 
option. A Windows Sockets implementation need aot support the use of keep-aiives: if 
it does, the precise semantics axe implementation-specific but should conform to section 
4.2.3.6 of R^FC 1 122: Requirements for Internet Hosts - Communication Layers. Lf a 
connection is dropped as the result of "keep-alives" the error code WSAENfc ik£SET is 
returned to any calls in progress on the socket, and any subsequent calls will fail with 
WSAENOTCONN. 

The TCP_N*ODELAY oprion disables the Nagle algorithm. The N'agle algorithm is 
used to reduce the number of small packets sent by a host by buffering unacknowledged 
send data until a full-size packet can be sent. However, far some a pp lie a nous this 
algorithm can Impede performance, and TCP^NODELAY may be used to rum it off. 
Application writers should not set TCP_N r ODELAY unless the impact of doing so is 
well-understood and desired, since setting TCP_NODELAY can have a significant 
negative impact of aerwork performance. TCP_NODELA Y is the only supported 
socket option which uses level IPPROTO_TCP; all other options use level 
SOL.SOOCET. 

Windows Sockets suppliers are encouraged (but not required) to supply ourput debug 
information Lf the SO_DEBUG option is set by an application. The mechanism for 
generating the debug inform ation and the form it takes are beyond die scope of this 
specification. 

The following options are supported for setsockoptO- The Type identifies the type of 
data addressed by oprval. 



Value 

SO.BROADCAST 

SO.DEBUG 
SO.DONTLINGER 



SCLDONTROUTE 

SOJCEEPALrVE 

SO.LINGER 

SO_OOB INLINE 

SO.RCVBUF 
SO REUSEADDR 



Type 
BOOL 

BOOL 
BOOL 



BOOL 

BOOL 

s cruet linger 

FAR • 

BOOL 

int 

BOOL 



Waning 

.Allow transmission of broadcast messages on the 
socket. 

Record debugging information. 

Dou't block close waiting for unseat data to be 

sent. Setting this option is equivalent to sertLng 

SOJJNGER with lonoff sec to zero. 

Don't route: send directly to interface. 

Send keepalives 

Linger on close Lf unsent data is present 

Receive out-of-band data in the normal data 
stream. 

Specify buffer size for receives 

.Allow the socket to be bound to an address which 

is already in use. (See bindQ.) x 
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SO.SNDBLT int 
TCP_NODELAY 'BOOL 



Specify buffer size for sends. 

Disables the Nagle algorithm for send coalescing. 



BSD options not supported for setsockopU) are: 





Ty?c 


Me in in 2 


SO.AOJLKLCONN 


BOOL 


Socket is Listening 


SO.ERROR 


Lot 


Get error status and clear 


SO.RCVLOWAT 


LQt 


Receive low water mark 


SO.RCVTTMEO 


Luc 


Receive timeout 


SO_SN*DLOWAT 


LQt 


Send low water marie 


SO.SNTOTMEO 


Lac 


Send timeout 


SOJTfPE 


int 


Type of the socket 






Set options Field in EP header. 



Return Value If no error occurs. setsockoptQ returns 0. Otherwise. .a value of SOCKET_ERROR is 
returned, and a specific error code may be retrieved by calling WSACetLastEnrorO. 



Error Codes WS AJs'OTTNTTLALISED 
WSAENFIDOWN 
WSAEFAULT 
WS AEENFROGRESS 
WSASNVAJL 
WSAENETRESET 
WS AENOFROTOOPT 



WSAENOTCONN 



WSAENOTSOCK 



A successful WSAStartupO must occur before 
Tiding rhic API. 

The Windows Sockets Implementation has detected 
that the network subsystem has failed. 

optval is not in a valid part of the process address 
space. 

A blocking Windows Sockets operation is in 
progress. 

level is not vaiid.^or the information in optval is not 
valid. 

Connection has timed out when SO.KFFP ALIVE is 
set. 

The option is unknown or unsupported. In 
particular. SO_BROADCAST is not supported on 
sockets of type SOCK.STREAM. while 
S O _ DO NTLINGER . SO.KEEP ALIVE, 
SO .LINGER and SO_OOB CSUNE are not 
supported on sockets of type SOCK_DGRAM. 

Connection has been reset when SO_KEEP ALIVE 
is set. 

The descriptor is not a socket- 



See Also 



bindQ. getsockoptO. ioctlsocketQ. socketO. WSAAsyocSelectO. 
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4.1.22 shutdown<) 

Description Disable sends and/or receives oq a socke:. 
"include <winsock.h> 

i nt PASCAL FAR shutdown ( SOCKET s t mt how ); 



1S 



20 



25 



hew 



A descriptor identifying a socket. 

A flag that describes what rypes of oper3tioa will qo longer be 
allowed. 



30 



Remarks shutdownO is used oa all types of sockets to disable recepdoa. transmission, or both. 

If how is 0. subsequent receives oa the socket w ill be disallowed. This has no effect on 
che lower protocol layers. For TCP. die TCP window is not changed and Incoming data 
will be accepted (but not acknowledged) until the window 13 exhausted. For UDP. 
inco m i n g datagrams are accepted and queued. In no case will an I CMP error packet be 
generated. 

If ho w is 1. subsequent sends are disallowed. For TCP sockets, a FIN will be sent. 

Setting how to 2 disables both sends and receives as described above. 

Note that shutdownO does not ciose the socket, and resources attached to the socket 
will not be freed until cIosesocketQ is invoked. 
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Comments shutdownO does not block regardless of the SO_ LINGER serting on the socket. 

.An application should doc rely on being able to re-use a socket after it has been shut 
down. In particular, a Windows Sockets implementation is not required to support the 
use of coouectO on such a socket 

Return Value If no error occurs. shutdownO returns 0. Otherwise, a value of SOCKET, ERROR is 
re curried, and a specific error code may be retrieved by c alling WSAGetLastErrorQ. 



Error Codes 
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WSANOTMT1ALISED 

WSAENETDOWN 

WS AEENVAL 
WSAEENPROGRESS 

WSAENOTCONN 

WSAENOTSOCK 



A successful WSAStartupO must occur before 
using rhU .API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

how is not valid. 

A blocking Windows Sockets operation is in 
progress. 

The socket is not connected (SOCK_STREAM 
only). 

The descriptor is not a socket. 
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s 

See Also coanectO. socketQ- 
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w 



4.1.23 socket() 
Description Creaie a socket. 



^include <winsock.b> 

SOCKET PASCAL FAR socket ( Lnt af, tnt type, int protocol ): 



is 
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type 



protocol 



An address format specification. The only format currendy supported 
is PF_ENhl . wtuch is the ARPA Internet address format. 

A type specification for the new socket. 

A particular protocol to be used with the socket, or 0 if the caller does 
not wish to specify a protocol. 



Remarks socketO allocates a socket descriptor of the specified address family, data type and 

protocol, as well as related resources. If a protocol is not specified (i.e. equal to 0). the 
default for the specified connection mode is used. 

Only a single protocol exists to support a particular socket type using a given address 
format. However, the address family may be given as AF_UNSPEC (unspecified), in 
which case the protocol parameter must be specified. The protocol number to use is 
particular to the "communication domain" in which communicadon is to take pl^e. 

The following type specifications are supported: 



SOCK^STREAM 



SOCK_DGRAM 



Provides sequenced, reliable, two-way, connection- 
based byte screams with an out-of-band data 
aransmission mechanism. Uses TCP for the Internet 
address family. 

Supports datagrams, which are cooneccioale ss. 
unreliable buffers of a fixed (typically small) 
maximum length. Uses UDP for the Internet address 
family. 



Sockets of type SO CK_ STREAM are full-duplex byte streams. A stream socket must 
be in a connected state before any data may be sent or received on it. A con motion to 
another sodket is created with a connectO call. Once connected, data may be 
transferred iming sendO and recvO calls. When a session has been completed, a 
ciosesocketO must be performed. Out-of-band data may also be cransmitted as 
described in sendO and received as described in recvO- 

The communications protocols used to implement a S0CK_ STREAM ensure that data 
is not lost or duplicated. Ef data for which che peer protocol has buffer space cannot be 
successfully transmitted within a reasoaable length of time, the connection is 
coasidered broken and subsequent calls will fail with the error code set to 
WSAETIMEDOUT. 
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50CK_DGRAM sockecs allow sending and receiving of datagrams to and from 
arbitrary peers using seadtoO 3nd recvfromQ. Lf such a socket is conaect()ed to a 
specific peer, datagrams may be send to that peer seodO and may be received from 
t'onJy) this peer using recvQ. 

Return Value Lf no error occurs. socketO returns a descriptor referencing the aew socket. Otherwise. 

a value of CNV AL ED _ SOCKET is renamed, and a specific error code may be retrieved 
by calling VVSAGetLastErrorf). 



Error Codes W S ANOTTNTTL-VL IS ED 

WS AENHETDOWN 

WSAEAFNOSUPPORT 
WSAEINPROGRESS 

W'S AEMFELE 
WSAENOBLTS 



A successful VVSAStartupO must occur before 
using this .API. 

The Windows Sockets Implementation has detected 
Lhat the network subsystem has failed. 

The specified address family is not supported. 

A blocking Windows Sockets ope ran on is in 
progress. 

No more file descriptors are available. 

No buffer space is available. The socket cannot be 
created. 



WSAEFROTONOSUFTORT The specified protocol is not supported. 

WSAEPROTOTYPE The specified protocol is the wrong type for this 

socket. 

WSAESOCKTNOSUPPORT The specified socket type is not supported in this 

address family. 

See Also acceptO. bindO. coonectO. getsocknameO. getsockoptO. setsockoptO. listeoQ. recv(). 

recvfromO. selectQ. sendQ. sendtoQ, shutdowcQ. ioctlsocketQ- 
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4.2 Database Routines 
4.2.1 gethostbyaddr() 

Description Get hose information corresponding to an address. 
"Include <wiasock.h> 

struct bostent FAR • PASCAL FAR geihosrbyaddr ( coast char FAR • addr. int 
/c/7. int rype ); 



adJr A pointer to an address in nerwork byte order. 

Un T^ e length of the address, which must be 4 for PF_CN~ET addresses. 

c }'P e The rype of the address, which must be PF_INET. 

Remarks gethostbyaddrO returns a pointer to the following sirucrure which contains the aame(s) 

and address which correspond to the given address. 

struct hoster.t ( 

char FAR * h_na^e ; 

char FAR * FAR * h_diiase3; 

shore h_addrt;ype; 

shore h_Iep.gch; 

char FAR * FAR * h_addr_lisc ; 

The members of this structure are: 
Element LIsagfi 

h_aame Official name of the host (PC). 

h_aiiases A NULL- termini ted array of alternate names, 

h.addrrype The rype of address being returned; for Windows Sockets this is 
always PF_INET. 

h Jengtb The length, in bytes, of each address; for FF_INET. this is always 4. 

h_addr_list A SULL-^nniriB ted list of addresses for the host. Addresses are 
returned in network byte order. 

The macro h,addr is defined to be h_addr_List[0] for compatibility with older software. 

The pointer which is returned points to a structure which is allocated by the Windows 
Sockets implementation. The application must never attempt to modify this structure or 
to free any of its components. Furthermore, only one copy of this sirucrure is allocated 
per thread, and so the application should copy any information which it needs before 
issuing any other Windows Sockets API calls. 



Return Value If no error occurs, gethostbyaddrO returns a pointer to the hostent structure described 
above. Otherwise it returns a NULL pointer and a specific error number may be 
retrieved by calling WS A GetLastE rrorO. 

Error Codes WSANOTTMTLALISED A successful WSAStartupO must occur before 

using this -API. 
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5 WSaENHTDOWN 

WSAKOST_NOT_FOt"NT) 
w WSATRY.AG.AIN 

WSANO_R£COVERY 

is 

WSANCLDATA 
WSA£INPROGR£SS 

20 

WSAEINTR 
See AJso VVSAAsyncGetHostByAddrQ. 
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The Windows Sockets im piemen taiioa has detected 
chat die aer/work subsystem has failed. 

Authoritative .Answer Host aot found. 

Noa- Authoritative Host aot found, or 
SERV"ERf.*UL. 

Noa recoverable errors, FORMERR. RFFT'SFn 
NOTES IP. 

Valid aame. qo data record of requested type. 

A blocking Windows Sockets operation is in 
progress. 

The (blocking) call was canceled via 
WSACanceLBIocicingCaUO. 

geLhostbynameQ. 
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10 



1S 
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4.2.2 gethostbyname() 

Description Get host inibrmadon corresponding :o a aosmame. 
^include <wiasocW.b> 

struct hostent FAR • PASCAL FAR gethostbyname ( const char FAR • ncme ); 



name A pointer to the name ot the hast. 

Remarks gethostbyaameO returns a pointer to a hostent s true cure as described under 

gethostbyaddrO- The contents of this structure correspond to the hostname name. 

The pointer which is returned points to a strucrure which is alloc axed by the Windows 
Sockets implementation. The application must never attempt to modify this strucrure or 
to free any of its components. Furthermore, only one copy of this structure is allocated 
per thread, and so the application should copy any information which it needs before 
issuing any other Windows Sockets API calls. 

A gethostbyuameO implementation must not resolve EP address strings passed to it. 
Such a request should be created exactly as if an unknown host name were passed. An 
applicadon with an CP address string to resolve should use inet_addrO to convert the 
string to an EP address, then gethostbyaddrO to obtain the hostent structure. 
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Return Value If no error occurs. getnostbynameO re rums a pointer to the hostent s true cure described 
above. Otherwise it re rums a NULL pointer and a specific error number may be 
retrieved by calling WSAGetLastErrorO 



Error Codes WS AN0TTNTT1AJJSED 

WS AENETDO WN 

WSAH0ST.N0T_FOUXD 
WSATRY_ AGAIN 

WSANO_ RECOVERY 

WSANCLDATA 
WSAEDSTPROORESS 

WSAEINTR 



A successful WSAStartupO must occur before 
n^ing this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

Authoritadve .Answer Host not found. 

Non-Authoritadve Host not found, or 
SERVERFAIL. 

.Von recoverable errors. FORMERR. REFUSED. 
N'OTTMP. 

Valid name, no data record of requested type. 

A blocking Windows Sockets operation is in 
progress. 

The (blocking} call was canceled via 
WSACancelBlockiogCallO. 
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See Also 



WSAAsyncGetHostByNameO. gethostbyaddrO 
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4.2.3 gethostname() 

Description Re cum the standard hose Qine for the local mac hine 
.^include <winsock.h> 

int PASCAL FAR gethostoanie ( char FAR ■ name, int nameien ); 

name A pointer to a buffer that will receive the host name. 

nameien The length of the buffer. 

Remarks This routine re aims the name of the local host into the buffer specified by the name 

parameter. The host oame is returned as a null- terminated string. The form of the host 
name is dependent on the Windows Sockets implementation- -it may be a simple host 
aame. or it may be a fully qualified domain name. However, it is guaranteed that the 
name returned will be successfully parsed by gethostbyoameO and 
VVSAAsyacGetHostByNameO. 

Return Value If no error occurs. gethostnameO re euros 0. otherwise it re nuns SOCKET^ ERROR and 
a specific error code may be retrieved by calling WSAGetLastErrorO. 

Error Codes WSAEFALTT The nameien parameter is too small 

W S ANOTTNTTLAL IS ED A successful WSAStartupO must occur before 

lining rhk .API. 

W'S AENfc. 1 DOWN The Windows Sockets implementation has detected 

that the network subsystem has failed. 

WSAQNPROGRESS A blocking Windows Sockets operation is in 

progress. 

See Also gethostbyoameO, VVSAAsyacGetHostByNameO. 
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4.2.4 getprotobyname() 

Description Get protocol uafonnacon corresponding :o a protocol name, 
^include <winsock.b> 

struct protoent FAR • PASCAL FAR getprotobyname ( const cfaar FAR - name ); 



name A pointer to a protocol aamc. 

Remarks getprotobvaameO reruras a pointer to the following structure which contains the 

name(s) and protocol aumber which correspond to the given protocol name. 

stz^zz pro: oenc i 

char ?A?» * p_r.ame; 

char FAR * FAR * p_aliases; 

shore p pro co ; 



The members of this s true aire are: 
Element Usage 

p_name Official name of the protocol. 

p_aliases A NLlX-terminft^d array of alternate names. 

p_proto The protocol number, in host byte order. 

The pointer which is returned points to a structure which is allocated by the Windows 
Sockets library. The application must never attempt to modify this s true aire or to tree 
any of its components. Furthermore only one copy of this structure is allocated per 
thread, and so the application should copy any information which it needs before 
issuing any other Windows Sockets API calls. 



Return Value If no error occurs. getprotobynarneO returns a pointer to the protoent structure 

described above. Otherwise it returns a NULL pointer and a specific error number may 
be retrieved by calling WSAGetLastErrorO. 



Error Codes 



WS A.\ OTTNTTIALISED 

WSAENETDOWN 

WSAi\0_RECOVERY 

WSANO.DATA 
WSAEOTPROGRESS 

WSAEINTR 



A successful WSAStartupO must occur before 

ngino th i_< API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

Noo recoverable errors. FORMERR, REFUSED. 
NOTIMP. 

Valid name, no data record of requested rype. 

A blocking Windows Sockets ope ran on is in 
progress. 

The (blocking) call was canceled via 
WSACancelBlockingCaUO. 
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See Also WSAAsyncGetProtoByNameO. getprotobvnumberi) 
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4.2.5 getprotobynumber() 

Description Get protocol uu'orrnarioQ corresponding to a protocol number. 
£ Include <wiasock.h> 

.struct protoent FAR • PASCAL FAR getprotobynumber ( int number ); 

number A protocol number, in host byte order. 

Remarks This function returns a pointer to a protoent strucrure as described above La 

getprotobynameQ. The contents of the strucrure correspond to the givea protocol 
number. 

The pointer which is returned points to a strucrure which is allocated by the Windows 
Sockets implementation. The application must never attempt to modify this structure or 
to free any of its components. Furthermore, only one copy of this structure is allocated 
per thread, and so the application shouid copy any information which it needs before 
issuing any other Windows Sockets API calls. 



Return Value If no error occurs. getprotobyii umber 0 rerurns a pointer to the protoent structure 

described above. Otherwise it returns a NULL pointer and a specific error number may 
be retrieved by calling WSAGetLastErrorO. 



Error Codes WS ANOTINTTTALISED 



WS AENETDO WN 



WSANCLRECOVERY 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

Non recoverable errors. FORMERR. REFUSED. 
NOTIMP. 



WSANCLDATA 
WSAEENPROGRESS 

WSAEINTR 



Valid name, no data record of requested type. 

A blocking Windows Seekers operation is In 
progress. 

The (blocking) call was canceled via 
WSACancelBIockingCaUO. 



See Also 



WSAAsvncGetProtoByNumberO. gerprotobfnameO 
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4.2.6 getservbyname() 

Description Get service information corresponding to a service oatce and protocol, 
^include <wins<x:k.h> 

struct s*rv*at FAR • PASCAL FAR gets*? rv byname I const char FAR • name. 
const char FAR 9 prate ); 



name A pointer to a service name. 

pro cn An optional pointer to a protocol nane. if this is NT fl I.. 

getservbynameO rerums the first service en cry for which Lae name 
matches the s.name or ooe of :he s_aliases. Otherwise 
getservbyoameO matches both the name and the pro to. 

Remarks getservbyoameO returns a pointer to the following scrucrune which contains the 

namei s) and service number which correspond to the given service name. 

st rue- server.: [ 

cr.ar FAJ* * s_r.a_T.e ; 

char T.^R r FAP. ' s_al:ases; 

she r: 3 cor:; 

char FAR* • 3-orjco; 



The members of this scrucnire are: 
Element Lfcass 

s_name Official name of the service. 

s_ aliases A NXTX- terminated array of alternate names. 

s_pon The port number at which die service may be contacted. Port 

numbers are re curried La aerwork byte order. 
s_proto The name of the protocol to use when contacting the service. 



The pointer which is returned points to a structure which is allocated by the Windows 
Sockets Library. The application must aever attempt to modify this structure ox to free 
any of its components. Furthermore only one copy of this srrucrure is allocated per 
thread, and so the application should copy any information which it "***yjs before 
issuing any other Windows Sockets API calls. 



Return Value If no error occurs. getservbynameO returns a pointer to the serveat structure described 
above. Otherwise it rerums a STILL, pointer and a specific error a umber may be 
retrieved by calling WSAGeLLastErrorO- 



Error Codes W S AN OTTNTTTAL IS ED 
W S AENETDO WN 
WSANO. RECOVERY 



A successful WS ASlartu pO must occur before 

using fhis APE. 

The Windows Sockets implementation has detected 
that the network subsystem has failed.- 

Nog recoverable errors. FORMERR. REFUSED. 
NOTTMP. 
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5 WSANCLDATA 

WS.\ED.TROGR£SS 

10 WSAEENTR 

?5 See AJso WSAAsyncGetServBv.NameO. 
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Valid name, no daia record ot requested type. 

A blocking Windows Sockets operation is in 
progress. 

The (blocking) coil was canceled via 
WSACancelBIockingCaUO. 

getservbyportf) 
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4.2.7 getservbyporiO 

Description Get service information correspocdiag to i port and p rococo I. 
^include <winsock.h> 

struct servent FAR * PASCAL FAR getservbyport ( int port, const char FAR 

pro to ); 



port The pon for a service. La network byte order. 

proto An optional pointer to a protocol aame. If this is NTJLL. 

getservbyportO returns '-he. First service entry for which the port 
matches the s_port. Otherwise getservbyportO matches both the port 
and the protc. 

Remarks getservbyportO returns a pointer a servent structure as described above for 

gelserv bynameQ. 

The pointer which is re aimed points to a strucrure which is allocated by the Windows 
Sockets implementation. The application must never attempt to modify this structure or 
to free any of its components. Furthermore, only one copy of this strucrure is allocated 
per thread, and so the application should copy any Information which it needs before 
issuing any other Windows Sockets API calls. 



Return Value If no error occurs, getservbyportO returns a pointer to the serve at structure described 
above. Otherwise it returns a NULL pointer and a specific error number may be 
retrieved by calling WS A GetLastErrorO. 



Error Codes 



WSANOTTSTTIALI5HD 

WS AENETDO WN 

WS ANO_RECO VERY 

WS ANO_D AT A 
WSAETNFROGRESS 

WSAJECNTR 



A successful WSAStartupO must occur before 

itdng thi< API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

Non recoverable errors. FORMERR, REFUSED. 
NOTTMP. 

Valid name, no data record of requested type. 

A blocking Windows Sockets operation is in 
progress. 

The (blocking) call was canceled via 
WSACancelBlockingCaHQ. 



See Also WSAAsyncGetServByPortO. getservbyoameO 
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4.3 Microsoft Windows-specific Extensions 
4.3.1 WSAAsyncGetHostByAddr() 

Description Get host information corresponding to id address - asynchronous version, 
^include <winsock.b> 

HANDLE PASCAL FAR WSAAsyncGetHostByAddr ( HWND hWnd: 
unsigned int ^ Msg, coast cbar FAR • addr t int Un. iat type, char FAR • duj\ int 
buflen ); 

hWnd The handle of the window wh_ich should receive a message when *_he 

asynchronous request completes. 

wMs% Tae message to be received when toe asynchronous request 

completes. 

addr A pointer to the network address tor the host. Host addresses are 

stored in network byte order. 

ten The length of the address, which must be 4 for FF.ENET. 

rype The type of the address, which must be FF_INET. 

huf A pointer to the data area to receive the hostent data. iNbte that this 

mast be larger than the size of a hostent structure. This is because the 
data area supplied is used by the Windows Sockets implementation to 
contain not only a hostent structure but any and all of ihe data which 
is referenced by members of the hostent structure. It is recommended 
Lhai you supply a buffer of MAXGETHO STSTR U CT bytes. 

buflen The size of data area buf above. 

Remarks This function is an asynchronous version of gethostbvaddrO. and is used to retrieve 

host name and address information corresponding to a network address. The Windows 
Sockets Implementation initiates the operation and returns to the caller immediately, 
passing back an asvpchron fms task hand If; which the application may use to identify ihe 
operation. When the operation is completed, the results (if any) are copied into the 
buffer provided by the caller and a message is sent to the application's window. 

When the asynchronous operation is complete the application's window hWnd receives 
message wMsg. The ™ Par am argument contains the asynchronous task handle as 
returned by the original function call. The high 16 bits of LP or am contain any error 
code. The error code may be any error as defined in winsockJi. An error code of zero 
indicates successful completion of the asynchronous operation. On successful 
completion, cite buffer supplied to the original function call contains a hostent structure. 
To access the elements of this structure, the original buffer address should be cast to a 
hostent s true aire pointer and accessed as appropriate. 

Note that if the error code Is WSAENOBUFS. it indicates that the size of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low 16 bits of IParam contain the of buffer required 
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co supply ALL (he requisite iniorriadon. If the application decides that the partial Jata 
:s inadequate, it may reissue the WSAAsyncGetHostByAddrO ruactioa call with a 
buffer large eaough to receive ai- the desired iniormacon (i.e. ao smaller than the low 
1 6 bits of IParam). 

The error code and buffer length should be extracted from the iParzm using the macros 
WSAGETAS YNCERROR and WSACETAS YNCBLTLEN. denned in winsock.h as: 



4~e f i - e W 5 AC ETA 5 \O.C S ?_=C 
vier;.-e WSACETAS VNC3LT L 



:-: :woro < : ? £ r a ~. , v 



The use of these macros will maximize the portability of the source code for the 
a pp Lie a a on. 

Return Value The re rum value specifies whether or not the asynchronous opera a on was success fuUv 
initiated. Note that it does not imply success or failure of the opera don iLseli. 

If the operation was successfully initiated. WSAAsyncGetHostByAddrO rerunis a 
nonzero value of type HANDLE which is the asynchronous task handle for the request. 
This value can be used in two ways. It can be used to cancel the operation using 
WSACanceLAsyncRequestO- It can also be used to match up asynchronous operations 
and completion messages, by examining the wPcram message argument. 

If the asynchronous operation could cot be initiated. WSAAsyncGetHostByAddrO 
rerunis a zero value, and a specific error number may be retrieved by calling 
WSAGetLastErrorO. 

Comments The buffer supplied to this function is used by the Windows Sockets implementation to 
construct a hostent structure together with the contents of data areas referenced by 
members of the same hostent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MXXGETHOSTSTRUCT 
bytes (as defined in winsock.h). 

Notes For 
Wlndows Sockets 

Suppliers It is the responsibility of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostMessageO operation fails, the 
Windows Sockets implementation must re-post that message as long as the window 
exists. 

Windows Sockets suppliers should use the WSAA1AKEASYNCREPLY macro when 
consrrucring the LP cram in the message. 

Error Codes The following error codes may be set when an application window receives a message. 

.As described above, they may be extracted from the LParam in the reply message using 
the WSAGETASYNGERROR macro. 



WSAENETDOWN 



The Windows Sockets implementation has detected 
that the network subsvstem has failed. 



WSAJENOBUFS 
WSAHOST.NOT.FOtfND 



No/insufficient buffer space is available 
Authoritative .Answer Host not found. 
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WSATOY. AGAIN 
WSANO ..RECOVERY 
WSANO DATA 



Noa- Authoritative Host qoc found, or 
SERVERFAIL. 

Noa recoverable errors. FORMERR REFUSED 
N'OTTMP. 

Valid name, no daia record of requested type. 



The following errors may occur at the time of the function call, and indicate that the 
asynchronous operation could aot be initialed. 



W S AN OTENTTTAL I S ED 



WSAENETDOWN 



WSAEENPROGRESS 



WS AEWO LT_D BLOCK 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has [ailed. 

A blocking Windows Sockets operation is in 
progress. 

The asynchronous operation cannot be scheduled at 
this rime due to resource or other constraints within 
the Windows Sockets implementation. 



gethostbyaddrQ, VVSACaucelAsyocRequestO 
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4.3.2 WSAAsyncGetHostByNameO 

Description Gt:t hosi information corresponding :o a hosaiaoe - asynchronous version, 
^include <win.MH:k.h> 

HANDLE PASCAL FAR vVSAAsvncCetHosiByN*ame( HWND hWnd. 
unsigned int -4fyy, const char FAR * name, char FAR • buf tat buHen.): 



hWnd The handle of the window which should receive a message when the 

asynchronous request completes. 

"-'Msg The message co be received when the asynchronous request 

completes. 

name A pointer to the aame of the host. 

bu f A pointer to the data area to receive the hostent dau. Note that this 

must be larger than the size of a hostent structure. This is because the 
dau area supplied is used by the Windows Sockets implementation to 
contain not onJy a hostent structure but any and all of the data which 
is referenced by members of the hostent structure. It is recommended 
thai you supply a buffer of MAXGETHOSTSTRUCT bytes. 

buflen The size of data area buf above. 

Remarks This function is an asynchronous version of gethostbyoameO. and is used to retrieve 

host name and address information corresponding to a hostname. The Windows 
Sockets implementation initiates the operation and returns to the caller immediately, 
passing back an asynchronous task hnnrfi* which the application may use to identify the 
operation. When the operation is completed, the results (if any) are copied into the 
buffer provided by the caller and a message is sent to the application's window. 

When the asynchronous operation is complete the application's window hWnd receives 
message wMsg. The ^Param argument contains the asynchronous task handle as 
returned by the original function call. The high 16 bits of IParam contain any error 
code. The error code may be any error as defined in mnsock Ji. An error code of zero 
indicates successful completion of die asynchronous operation. On successful 
completion, the buffer supplied to the original function call contains a hostent strucrure. 
To access the elements of this s one aire, the original buffer address should be cast to a 
hostent structure pointer and accessed as appropriate. 

Note that if the error code is WSAENOBUFS. it indicates that the size of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low 16 bits of IParam contain the size of buffer required 
to supply .ALL the requisite information. If the application decides that the partial dau 
is inadequate, it may reissue the WSAAsyncGetHostByNameO function call with a 
buffer large enough to receive all the desired information (i.e. no smaller than the low 
16 bits of IParam). 

The error code and buffer length should be extracted from the IParam using the macros 
WS AG ETAS YMCERROR and W S AG ETAS YNGB LTLEN . defined in winsock.fa as: 
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, ~I I- [ - e wSAJITAi'^JCBLT IE:-.' ( "-Pir.fL.Ti) 1C*CRC ( i?ar£3) 

The use of ihese macros will maximize the portability of the source code for the 
application. 



Return Value The return value specifies whether or aot the asynchronous operatioa was "successfully 
initiated. Note that it does OQL jnply success or failure of the operation itself. 

if the operation was successfully initialed. VVSAAsyncGetHostBy.NanieO returns a 
Gooxero value of type HANDLE which is the asynchronous task handle for the request. 
This value can be used in two ways. It can be used to cancel the operatioa using 
WSACancelAsyncRequestO- It can also be used to match up asynchronous operations 
and completion messages, by examining the wParam message argument. 

If the asynchronous operation could not be initiated. WSAAsyncGetHostByNameO 
.-cruras a zero value, and a specific error number may be retrieved by c a ll in g 
WSAGetLastErTorO. 

Comments The buffer supplied to this function is used by the Windows Sockets implementation to 
construct a bos tent structure together with the contents of data areas referenced by 
members of the same hostent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MAXGh 1 riO ST STRUCT 
bytes (as defined in winsockJi). 

Notes For 
Windows Sockets 

Suppliers It is the responsibiiiry of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostMessageO operation fails, the 
Windows Sockets Implementation must re-post that message as long as the window 
exists. 

Windows Sockets suppliers should use the WSAMAKEASYNCREFLY macro when 
coos true ting the iParam in the message. 

Error Codes The following error codes may be set when an application window receives a message. 

As described above, they may be extracted from the IParam in the reply message using 
the WSAGETASYNCERROR macro. 



WS AENETDO WN 

WSAENOBUFS 

WSAH0ST_NOT_F0UND 

WSATRY.AGAIN 

WSANO_R£COVERY 



The Windows Sockets implementation has detected 
that the nerwork subsystem has f&il^d. 

No/insufficieat buffer space is available 

Authoritative .Answer Host not found. 

Non- Authoritative Host not found, or 
SERVER? AIL. 

Non recoverable errors. FOR-MERR. REFUSED, 
NOTTMP. 
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Valid name, no data record of requested cype. 



The following errors may occur at cbe time of the runctioa call, and indicate that the 
asynchronous operation could aot be undated. 



70 



W S AN 0 TTNTTIAL I S ED 



A successful VVSAStarrupO must occur before 
using this .API. 



15 



20 



See AJso 



WS.AENETDOWN 



WSAETNPROGRESS 



WS AEWO UUD B LOCK 



The Windows Sockets implementation has detected 
that the aecwork subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 

The asynchronous operation cannot be scheduled at 
this time due to resource or other constraints within 
Lhe Windows Sockets implementation. 



gethostbynameO. VVSACanceLAsyncRequestQ 
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4.3.3 WSAAsyncGetProtoByNameQ 

Description Get protocol ktiornutioa corrcspoacLng to a protocol n.ime - asynchronous version, 
^include <winsock.b> 

HANDLE PASCAL FAR VVSA AsyncGetProtoByNarne < HWND hWnd % 
unsigned int ^V*?. const char FAR • name, char FAR • huf\ int buften,): 

hWnd The handle or the window which should receive a message whea "-he 

asy-Qchroaous request completes. 

wbfsg The message to be received whea the asynchronous request 

completes. 

name A pointer to the protocol name to be resolved. 

buf A pointer to the data area to receive the protoent data. Note that this 

must be larger than the size of a protoent structure. This is because 
the da La area supplied is used by the Windows Sockets 
implementation to contain not only a protoent structure but any and 
ail of the data which is referenced by members of the protoent 
structure. Et is recommended that you supply a buffer of 
MAXGETHOSTSTRUCT bytes. ' 

buften The size of data area buf above. 

Remarks This function is an asynchronous version of getprotobynameO. ^d is used to retrieve 

the protocol nami* and number corresponding to a protocol name. The Windows 
Sockets implementation initiates the operation and returns to the caller immediately, 
passing back an asynchronous task handle which the application may use to identify the 
operatioa. When the operation is completed, che results (if any) are copied into the 
buffer provided by the caller and a message is sent to the application's window. 

Whea the asynchronous operation is complete the application's window hWnd receives 
message wMsg. The w Par am argument contains the asynchronous task handle as 
returned by the original function call. The high 16 bits of LP or am contain any error 
code. The error code may be any error as defined in winsock-h. An error code of zero 
indicates successful completion of the asynchronous operatioa. On successful 
completion, the buffer supplied to the original function call contains a protoent 
structure. To access the elements of this structure, the original buffer address should be 
cast to a protoent structure pointer and accessed as appropriate. 

Note that if the error code is WS AEN'OBUTS. it indicates that the size of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low L6 bits of LP or am contain the size of buffer required 
to supply ALL the requisite information. U the application decides that the partial data 
is Inadequate, it may reissue the WSA.AsyocGetProtoBytNameO function call with a 
buffer large enough to receive all the desired information (i.e. no smaller than the low 
16 bits of IParam). 

The error code and buffer length should be extracted from the IParam using the macros 
WSAGETAS YNCERROR and WSAGETASYNCBUFLEN. defined in winsock.h as: 
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The use of these macros will maximize the portability of the source code for the 
application. 



Return Value The return value specifies whether or not the asynchronous operatioa was successfully 
undated. Note thac it does uoj Imply success or failure of the operation itself. 

If the operatioa was successfully initiated. WSAAsyncGetProtoByNaineO returns a 
nonzero value of rype HANDLE which is the asynchronous task handle for the request. 
This value can be used in two ways. It can be used to cancel the operation using 
WSACanceLAsyncRequestO. It can also be used to match up asynchronous operations 
and completion messages, by examining the ^ Par am message argument. 

If the asynchronous operatioa could not be initiated. YVSAAsyncGetProtoByNameO 
returns a zero value, and a specific error number may be retrieved by calling 
WSAGetLast£nrorO. 

Comments The buffer supplied to this function is used by the Windows Sockets implementation to 
cans cruet a protoent s true cure together with the contents of data areas referenced by 
members of the same protoent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of ax least MAX GETTHO ST STRUCT 
bytes (as defined in wiosock.h). 

Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets implementation to ensure that messages 

are successfully posted to the application. If a PostMessageO opera don fails, the 
Windows Sockets implementation must re-post that message as long as the window 
exists. 

Windows Sockets suppliers should use the W S AMAKEA S YNCREPL Y macro when 
construe ring the IP cram in the message. 

The following error codes may be set when an applicadon window receives a message. 
As described above, they may be extracted from the IParam in the reply message using 
the W SAG ETAS YNCERROR macro. 



Error Codes 



WSAEXETDOWN 

WSAENOBUFS 
WSAHOST„.VOT_FOLTND 
WSAT"RY_ AGAIN 

WSANO.RECOVERY 



The Windows Sockets Lm piemen tan on has detected 
that the network subsystem has failed. 

No/insufficient buffer space is available 

Authoritative Answer Host not found. 

N'oo- Authoritative Host not found, or 
SERVERJvML. 

Noa recoverable errors. FORMERR. REFUSED. 
NOTTMP. 
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WSANO.DATA 



Valid oarne, no data record of requested type. 



The following errors may occur at the time of the function call, and indicate chat die 
asynchronous operation could not be initiated. 



WSANOTINTrLAJLISED 
WSAENETDOWN 
WSAEINPROGRESS 
WS AEWO UUD B LOCK 



A successful WSAStartupO caust occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 

The asynchronous operation cannot be scheduled at 
this rinrg due to resource or other constraints within 
the Windows Sockets Implementation. 



See Also 



gerprotobynameO. VVSACancelAsyncRequestO 
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5 4.3.4 WSAAsyncGetProtoByNumber() * 

Description Get protocol information corresponding co a protocol aumber - asynchronous version. 

# include <winsock.h> 

70 HANDLE PASCAL FAR WSAAsyncGetProtoByNurnber ( HWND hWnd % 

unsigned Lot wMsg, in t number, cbar FAR * buf lot buflen ); 

HWnd The handle of the window which should receive a message when the 

75 asynchronous request completes. 

*>Msg The message to be received when the asynchronous request 

completes. 

20 number The protocol number to be resolved, in host byte order. 

buf A pointer to the data area to receive the protoent data. Note that this 

must be larger than the size of a protoent structure. This is because 
the data area supplied is used by the Windows Sockets 
25 implementation to contain not only a protoent structure but any and 

all of the data which is referenced by members of the protoent 
structure. It is recommended that you supply a buffer of 
MAXGETHOST STRUCT bytes. 
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buflen The size of data area buf above. 

Remarks This function is an asynchronous version of getprotobyn umber 0. and is used to 

retrieve the protocol name and aumber corresponding to a protocol number. The 
Windows Sockets implementation initiates the operation and returns to the caller 
immediately, passing back an asynchronous fff^k hflnfllfi which the application may use 
to identify the operation- When the operation is completed, the results (if any) are 
copied into the buffer provided by the caller and a message is sent to the application's 
window. 

When the asynchronous operation is complete the application s window hWnd receives 
message *>Msg. The wParam argument contains Che asynchronous t**k handle as 
reruraed by the original function call. The high 1 6 bits of LP or am contain any error 
code. The error code may be any error as defined in winsock-b. An error code of zero 
indicates successful completion of the asynchronous operation. On successful 
completion, the buffer supplied to the original function call contains a protoent 
structure. To access the elements of this structure, the original buffer address should be 
cast to a protoent structure pointer and accessed as appropriate. 

Note that if the error code is WSAjD^OBUTS. it indicates that the size of die buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low 16 bits of LP or am contain the size of buffer required 
to supply. ALL the requisite information. If the application decides that the partial data 
is inadequate, it may reissue the WSAAsyncGetProtoByNumberO function call with a 
buffer large enough to receive all the desired information (Le. no qtmiUr rh«n the low 
16 bits of LParam). 



93 



EP 0 770 958 A1 



WSAAsyncGetProtoByNumb er 80 

The error code and buffer length should be extracted from the LParam usina the macros 
WSAGETAS YNCERROR and WSAGETASYNCBUPLEN. defined in winsock.h as 

♦ define WSAGETASrNCSRRCRUParara) HrwOMno.r^, 
•de^ne wsAGETASWCSOTLENUParan) wSSjfp^S 

The use of these macros will maximize the portability of the source code for the 
application. 



Return Value The return value specifies whether or not the asynchronous operation was successfully 
■moated. Note that it does 001 imply success or failure of the operation itself. 

If the operanon was successfully initiated. WSAAsyncCetProtoBjNumberO returns a 
nonzero value of type HANDLE which is the asynchronous task handle for the request 
This value can be used in two ways. It can be used to cancel the operanon using 
WSACancelAsyncRequestO. It can also be used to match up asynchronous operadoos 
and completion messages, by ex aminin g the w Par am message argument. 

If the asynchronous operadon could not be initiated. WSAAsyncGetProtoByNumberO 
returns a zero value, and a specific error number may be retrieved by callina 
WSAGetLastErrorO. 

Comments The buffer supplied to this function is used by the Windows Sockets implementation to 
construct a protoent Structure together with the contents of data areas referenced by 
members of the same protoent structure. To avoid die WSAENOBUFS error noted 
above, the application should prov ide a buffer of at least MAXGETHOSTSTR UCT 
bytes (as defined in winsockJi). 

Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostMessageO operation fails the 
Windows Sockets implementation nUiSi re-post that message as long as the window 
exists. 



Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when 
constructing the LParam in the message. 

Error Codes The lowing error codes may be set when an application window receives a message 

£ issssssa ss* - from *■ * aram m *■ rep,y — » 

WSAENETDOWN The Windows Sockets implementation has detected 

that the network subsystem has failed. 

WSAENOBUFS No/insuff.cient buffer space is available 

WSAHOST_NOT_FOUND Authoritative Answer Host not found. 

WSATRY_ AGAIN Non-Authoritative Host not found or 

SERVERFAJL. 



94 



EP 0 770 958 A1 



WSAAsyncGetProtoByNumb^r 81 



10 



15 



20 



WSANO.RECOVERY 



WSANO DATA 



Nog recoverable errors. FORMERR. REFUSED. 
NOTIMP. 

Valid Qame. qo data record of requested type. 



The following errors may occur ac the dine of the function call, and indicate that the 
asynchronous operation could not be initiated. 



WS ANOTTNTTlAL IS ED 
WSAENETDOWN 
WSAEINPROGRESS 
WS AEWOULDBLOCK 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A bloc Icing Windows Sockets operation is in 
progress. 



25 



See Also 



The asynchronous operation cannot be scheduled at 
this time due to resource or other constraints within 
the Windows Sockets implementation. 
gerprotobynumberQ. WSACancelAsyncRequestO 
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4.3.5 WSAAsyncGetServByName() 

Description Get service information corresponding to a sen/ ice dime and port - asynchronous 
version. 

^include <winsock.b> 

HANDLE PASCAL FAR WSAAsyacCetServByName ( HWND hWnd, . 
unsigned int *>Msg f const char FAR • name, const chax FAR • proto % char FAR • 
buf, int btiflen ); 

hWnd The handle of the window which should receive a message when the 

asynchronous request completes. 

wMsg The message to be received when the asynchronous request 

completes. 

A pointer to a service name. 

A pointer to a protocol name. This may be NULL, in which case 
WSAAsyocGetServByNameO will search for the first service entry 
for which sjiame or one of the sjaiiases matches the given name. 
Otherwise WSAAsyncGetServByNameO matches both name and 

proto. 

A pointer to the data area to receive the servent data. Note that this 
must be larger than the size of a servent structure. This is because the 
data area supplied is used by the Windows Sockets implementation to 
contain not only a servent structure but any and all of the data which 
is referenced by members of the servent structure. It is recommended 
that you supply a buffer of MAXGjETHO ST STRUCT bytes. 

buflen The size of data area buf above. 

Remarks This function is an asynchronous version of getservbynameO. and is used to retrieve 

service information corresponding to a service name. The Windows Sockets 
implementation initiates the operation and returns to the caller immediately, passing 
back an nwnrhmnmit r»<:k hwnrilp which the application may use to identify the 
operation. When the operation is completed, the results (if any) are copied into the 
buffer provided by the caller and a message is sent to the application's window. 

When the asynchronous operation is complete the application's window hWnd receives 
message *>Msg. The ^ Par am argument contains the asynchronous task handle as 
returned by the original function call. The high 1 6 bits of LP or am contain any error 
code. The error code may be any error as defined in winsock Ji. An error code of zero 
indicates successful completion of the asynchronous operation. On successful 
completion, the buffer supplied to the original function call contains a hostent structure. 
To access the elements of this structure, the original buffer address should be cast to a 
hostent structure pointer and accessed as appropriate. 

Mote that if the error code is WSAENOBUFS, it indicates that the size of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information, In this case, the low 16 bits of IP a ram contain the size of buffer required 



proto 



buf 
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to supply ALL the requisite Inform a do a. If the appLicaaoa decides that the paniai data 
is Inadequate, it may reissue the WSAAsyncGetServByNameO function call with a 
buffer large enough to receive alJ the desired information (i.e. ao smaller than tbe low 
16 bits of IParam). 



The error code and buffer length should be extracted from the IParam using the macros 
WSAGETASYNCERROR and WSAGETASYNCBUFLEN. defined in winsock.h as: 

^define W5AGETASYNCER3.0R ( LParair.) HI WORD (IParam) 

#define W 5 AGE TAS YNCB ITT LEN ( IParam) LOWORO ( IParam) 

The use of these macros will maximize the portability of the source code for the 
application. 



Retum Value The re rum value specifies whether or not the asynchronous operation was successfully 
Lai dated. Note that it does nQL imply success or failure of the operadon itself. 

If the operadon was successfully initiated. WSAAsyncGetServByNameO returns a 
nonzero value of type HANDLE which is the asynchronous task handle for the request. 
This value can be used in two ways. It can be used to cancel the operation using 
WSACajoceLAsyncRequestO. It can also be used to match up asynchronous operations 
and completion messages, by examining the ^ Par am message argument. 

If the asynchronous operation could not be initiated. WSAAsyncServByNameO re rums 
a zero value, and a specific error number may be retrieved by calling 
WS A GetLast£rTorO. 

Comments The buffer supplied to this function is used by the Windows Sockets implementation to 
coos cruet a hostent structure together with the contents of daia areas referenced by 
members of the same hostent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MAX Oh. I HOSTSTRUCT 
bytes (as drfinffri in winsock.h). 



Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets implementation co ensure thai messages 
are successfully posted to the application. If a PostM essageO operation fails, the 
Windows Sockets Implementation must re-post that message as long as the window 
exists. 



Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when 
constructing the IParam in the message. 

Error Codes The following error codes may be set when an application window receives a message. 

As described above, they may be extracted from the IParam in the reply message using 
the WSAGETASYNCERROR macro. 



WSAENETDOWN The Windows Sockets implementation has detected 

that the network subsystem has failed. 

WSAENOBUFS No/insufficient buffer space is available 
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30 



WSAHOST.NOT.FOLTND 
WSATRY_AGAIN 

WSANO.RECOVERY 

WSANCLDATA 



Authoritative Answer Host not found. 

Non-Authoritative Host not found, or 
SERVERFAIL. 

N'on recoverable errors. FORMERR. REFUSED. 

Nomip. 

Valid name, oo data record of requested type. 



The foLlowing errors may occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. 



WSANOTTNTTTAL1SED 
WSAENFTDOWN 
WSAEENPROGRESS 
WSAEWOULDBLOCK 



A successful WSAStartupO n*ust occur before 

ncing tht< API. 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets ope rati on is in 
progress. 

The asynchronous operation cannot be scheduled at 
this rin-M* due to resource or other constraints within 
the Windows Sockets implementation. 



See Also 



getservbynameO. WSACancelAsyncRequestQ 
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4.3.6 WSAAsyncGetServByPortO 

Description Get service Loformation corresponding to a port and protocol - asynchronous version, 
^include <winsock.h> 

HANDLE PASCAL FAR WSAAsyacGetServByPort ( HWND HWnd % 

unsigned int wMsg, int port, coast char FAR • proto, char FAR • buf, int buflen ); 

hWnd The handle of the window which should receive a message when the 

asynchronous request completes. 

wMsg The message to be received when the asynchronous request 

completes. 

port The port for the service, in oerwork byte order. 

pro co A pointer to a protocol name. This may be NULL, in which case 

WSAAsyncGetServByPortO will search for the first service en cry for 
which s jtort maich the given port. Otherwise 
WSAAsyncGetServByPortO matches both port and proto. 

buf A pointer to the data area to receive the servent da La. Note that this 

must be larger than the size of a servent structure. This is because the 
da La area supplied is used by the Windows Sockets implementation to 
contain not only a servent structure but any and ail of the data which 
is referenced by members of the servent structure. It is recommended 
that you supply a buffer of MAXGETHOSTSTRUCT bytes. 

buflen The size of data area buf above. 

Remarks This function is an asynchronous version of getservbyportQ. and is used to retrieve 

service information corresponding to a port number. The Windows Sockets 
implementation initiates the operation and returns to the caller immediately, passing 
back an asynchronous task handle which the application may use to identify the 
operation. When the operation is completed, the results (if any) are copied into the 
buffer provided by the caller and a message is sent to the application's window. 

When the asynchronous operation is complete the application's window hWnd receives 
message wMsg. The ™ Par am argument contains the asynchronous task handle as 
returned by the original function call. The high 16 bits of IP or am contain any error 
code. The error code may be any error as defined in winaockJi. An error code of zero 
indicates successful com pled on of the asynchronous operation. On successful 
completion, the buffer supplied to the original function call contains a servent structure. 
To access the elements of this structure, the original buffer address should be cast to a 
servent structure pointer and accessed as appropriate. 

Note that if the error code is WSAENOBUFS. it indicates that the size of the buffer 
specified by buflen in the original call was too small to contain all the resultant 
information. In this case, the low 16 bits of LP or am contain the size of buffer required 
to supply ALL the requisite information. If the application decides that the partial data 
is inadequate, it may reissue the WSAAsyncGetServByPortO function call with a 
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buffer large enough to receive all the desired information (i.e. no smaller chan the low 
1 6 bits of IParam). 

The error code and buffer length should be extracted from the IParam using the macros 
WSAGETASYNCERROR and WS AGET AS YNCB UFLEN. defined in wiosock.h as: 

f define WSAGETASYNCERROR ( IParam) HIWORD ( lParan) 

^define WSAGETASYNCBUFLEN ( lParar.) LOWORD < lParajn) 

The use of these macros will maximize the portability of the source code for the 
application. 



Return Value The return value specifies whether or not the asynchronous operation was successfully 
initiated. Note that it does OQi imply success or failure of the operation itself. 

If the operation was successfully initiated, WSAAsyocCetServByPortO returns a 
nonzero value of type HANDLE which is the asyockroaous task handle for the request. 
This value can be used in two ways. It can be used to cancel the operation using 
WSACancelAsyncRequestO- It can also be used to match up asynchronous operations 
and completion messages, by examining the ^ Par am message argument. 

If the asynchronous operation could not be initiated, WSAAayucGetServByPortO 
returns a zero value, and a specific error number may be retrieved by calling 
WSAGetLastEnrorO. 



Comments 



The buffer supplied to this function is used by the Windows Sockets implementation to 
cons cruet a servent structure together with the contents of data areas referenced by 
members of the same servent structure. To avoid the WSAENOBUFS error noted 
above, the application should provide a buffer of at least MAXGETHOSTSTRUCT 
bytes (as defined in wiosock.h). 

Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets implementation to ensure that messages 
are successfully posted to the application. If a PostM essageO operation fails, the 
Windows Sockets impl emen tation must, re-post that message as long as the window 
exists. 



Error Codas 



Windows Sockets suppliers should use the WS AMAKEASYNCREFLY macro when 
constructing the IParam in the message. 

The following error codes may be set when an application window receives a message. 
As described above, they may be extracted from the IParam in the reply message using 
the WSAGETASYNCERROR macro. 



WSAENETDOWN 

WSAENOBUFS 
WSAHOST_NOT_FOUND 



The Windows Sockets Implementation has detected 
that the network subsystem has fasled. 

No/Insufficient buffer space is available 

Authoritative Answer Host not found. 
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See Also 



WSATRY,AGAIN 

WSANO.RECOVERY 

WSANO.DATA 



Non- Authoritative Host qoc found, or 
SERVERFAIL. 

Noa recoverable errors. FORMERR. REFUSED, 
NOTIMP. 

Valid name, qo daia record of requested type. 



The following errors may occur at the time of the function call, and indicate that the 
asynchronous operation could not be Lni dated. 



WS ANOTINmALISED 
WSAENFTDOWN 
WSAEENPROGRESS 
WSAEWOULDBLOCK 



A successful WSAStartupO must occur before 
using this API. 

The Windows Sockets Implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 

The asynchronous operation cannot be scheduled at 
this rime due to resource or other constraints within 
the Windows Sockets implementation. 
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4.3.7 WSAAsyncSelect() 

Description Request event notification for a socket, 
^include <winsock.h> 

int PASCAL FAR WSAAsyncSelect ( SOCKET j, HWND hWnd. 
unsigaed int vwV/j£, long (Event ); 



s A descriptor identifying the socket for which event notification is 

required. 

hWnd A handle identifying the window which should receive a message 

when a network event occurs. 

wMsg The message to be received when a network event occurs. 

t Event A bitmask which specifies a combination of network events in which 

the application is interested. 

Remarks This function is used to request that the Windows Sockets DLL should send a message 
to the window hWnd whenever it detects any of the network events specified by the 
(Event parameter. The message which should be sent is specified by the wMsg 
parameter. The socket for which nodficarioo is required is identified by s. 



This function automatically sets socket s to non- blocking mode. 

The (Event parameter is constructed by or'ing any of the values specified in the 
following List. 



Value Nfenning 

FD_READ Want to receive notification of readiness for reading 

FD_WRITE Want to receive notification of readiness for writing 

FD_OOB Want to receive notification of the arrival of out-of-band data 

FD_ACOEFT Want to receive notification of irjcoming connections 

FD^CONNECT Want to receive notification of completed connecdoa 

FD_CL0SE Want to receive notification of socket closure 



Issuing a WSAAsyncSelectO for a socket cancels any previous WSAAsyucSelectO for 
the same socket. For example, to receive notification for both reading and writing, the 
application must call WSAAsyncSelectO with both FD_READ and FD_WRJTE, as 
follows: 

rc - WSAAsyncSelect (3, hWnd, wMsg, FD_READ I FD_WRITE) ; 

It is not possible to specify different messages for different events. The following code 
will aot work; the second call will cancel the effects of the first, and only FD_WRTT~E 
events will be reported with message wMsg2: 

rc =- WSAAsyncSelect (3, hWnd. vMsgl, FD_RZAD) ; 
re ~ WSAAsyncSelect (3, hWnd, wttsg2, FD_WRITE) ; 
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To cancel ail notification - i.e., to indicate that che Windows Sockets implementation 
should send no further messages related to network events on the socket - lEvent should 
be set to zero. 

rc » WSAAsyncSelect (s, hWnd, 0, 0); 

Although In this instance WSAAsyncSelectO immediately disables event message 
posting for the socket, it is possible that messages may be waiting in the application's 
message queue. The application must therefore be prepared to receive network event 
messages even after cancellation. Cosing a socket with ciosesocketO also cancels 
WSAAsyncSelectO message sending, but the same caveat about messages in the queue 
prior to the ciosesocketO still applies. 

Since an accepted socket has the same properties as the listening socket used to 
accept it. any WSAAsyocSelectO events set for the listening socket apply to the 
accepted* socket. For example, if a listening socket has WSAAsyncSelectO events 
FD ACCEPT. FD READ, and FD.VVRJTE. then any socket accepted on thai listening 
socket will also have FD_ ACCEPT. FD_R£AD. and FD_WRJTE events with the same 
wMsg value used for messages. If a different wMsg or events are desired, the 
application should call WSAAsyocSelectO. passing the accepted socket and the desired 
new information. 7 

When one of the nominated network events occurs on the specified socket s t the 
application's window hWnd receives message *>Msg. The wParam argument identifies 
the socket on which a network event has occurred. The low word of IP or am specifies 
the network event that has occurred. The high word of IParam contains any error code. 
The error code be any error as defined in winsock.b. 

The error and event codes may be extracted from the IParam using the macros 
WSAGETSELECTERROR and WS AGETSELECTE VENT, defined in winsock.b as: 

#define WSAGETSELECTERROR ( IParam) HI WORD ( IParam) 

#define W S AGETSELECTE VENT ( IParam) LO WORD ( IParam) 

The use of these macros will maximize the portability of the source code for the 
application. 

The possible network event codes which may be returned are as follows: 

Yahie M»«nin<r 

FD_READ Socket s ready for reading 

FD_ WRITE Socket s ready for writing 

FD_OOB Ouc-of-band data ready for rea din g on socket s. 

FD_ACCEPT Socket s ready for accepting a new incoming connection 

FCLCONNECT Connection on socket s completed 

FD~ CLOSE Connection identified by socket s has been closed 



? Note that there is a ^in g window between the acceptO call and the call to WSAAsyncSelectO to 
change the events or wMsg. An application which desires a different wMsg for che listening and 
accepted sockets should ask for only FD. ACCEPT events on the listening socket, then set appropriate 
events after the acceptO. Since FD. ACCEPT is never sent for a connected socket and FD_R£AD. 
FD WRITE FD_OOB. and FDJXOSE are never sent for listening sockets, this will not impose 
difficulties. 
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Return Value The return value is 0 if the application's declaration of Interest in the network event set 
wis successful. Otherwise the value SOCKET_ER_ROR is returned, and a specific error 
number may be retrieved by calling WSAGelLast£rror(). 

Comments Although WSAAsyncSelectO can be called with interest in multiple events, the 
application window will receive a single message for each nerwork event. 

.As in the case of the select 0 function. WSAAsyocSelectO will frequently be used to 
determine when a daia transfer operation (seodQ or recvO) can be issued with the 
expectation of immediate success. Nevertheless, a robust application must be prepared 
for the possibility that it may receive a message and issue a Windows Sockets API call 
which re rums WS AEWOULDBLOCK immediately. For example, the following 
sequence of events is possible: 



(i) 


data arrives on socket s; Windows Sockets posts WSAAsyncSelect 




message 


(u) 


application processes some other message 


(iii) 


while processing, application issues an ioctlsoc kerfs, FIONREAD...) 




and nonces that there is data ready to be read 


(iv) 


application issues a recv(s,...) to read the dau 


(v) 


application loops to process next message, eventually reaching the 




WSAAsyncSelect message indicating that data is ready to read 


(vi) 


application issues recvCs^..). which fails with the error 




WS AEWOULDBLOCK. 



Other sequences are possible. 



The Windows Sockets DLL will not continually flood an application with messages for 
a particular network event. Having successfully posted notification of a particular event 
to an application window, no further message(s) for thai network event will be posted to 
the application window until the application maJces the function call which implicitly 
reenables notification of that network event. 



Event Re^enahting function 

FD_R£AD recvO or recvfromO 

FD_WRJXE sendO or sendtoO 

FD.OOB recvO 

FD.ACCEPT acceptO 

FD_CONNECT NONE 

FD.CLOSE NONE 



Any call to the ree nab ling routine, even one which fails, results in reenabling of 
message posting for the relevant event. 

For FD.READ. FD_OOB. and FD_ ACCEPT events, message posting is "level- 
triggered." This means that if the reenabling routine is r*\\+4 and the relevant event is 
still valid after the call, a WSAAsyncSdectO message is posted to the application. 
This allows an application to be event-driven and not concern itself with the amount of 
data that arrives at any one time. Consider the following sequence: 
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w 



IS 



20 



25 



30 



35 



40 



45 



(i> 

(Li) 
(ui) 



Windows Sockets DLL receives 100 bytes of data oq socket s and 
posts an FD_R£AD message. 

The application issues recv( $, bufFptr, SO, 0) to read 50 bytes. 
The Windows Sockets DLL posts another FD.READ message since 
there is suU data to be read. 



With these semantics, an application need not read all available data in response to an 
FD_READ message-- a single recvO in response to each FD.REAJD message is 
appropriate. If an application issues multiple recvO calls in response to a single 
FD_R£AD. it may receive multiple FD_R_EAD messages. Such an application may 
wish to disable FD_RJEAD messages before starting the recvO calls by calling 
WSAAsyncSelectO with the FD.READ event not set. 

If an event is true when the application initially calls WSAAsyncSelectO or when the 
reenabling function is called, then a message is posted as appropriate. For example, if 
an application calls listenO. a. connect attempt is made, then the application calls 
WSAAsyncSelectO specifying that it wants to receive FD_ACCEFT messages for the 
socket, the Windows Sockets implementation posts an FD_ACCEPT message 
immediately. 

The FD_ WRITE event is handled slightly differently. An FD_WRITE message is 
posted when a socket is first connected with connectQ or accepted with acceptO. and 
then after a seodO or sendtoO fails with WSAEWOULDBLOCK and buffer space 
becomes available. Therefore, an application can assume that sends are possible 
starting from the first FD_ WRITE message and lasting until a send returns 
WSAEWOULDBLOCK. After such a failure the application will be notified that sends 
are again possible with an FD_WRJTE message. 

The FD_OOB event is used only when a socket is configured to receive out-of-band 
data separately. If the socket is configured to receive out-of-band data in-line, the out- 
of-band (expedited) data is treated as normal data and the application should register an 
interest in, and will receive. FD_READ events, noj FD_OOB events. An application 
may set or inspect the way in which out-of-band data is to be handled by using 
setsockoptO or getsockoptO for the SO_OOB INLINE option. 

The error code in an FD_ CLOSE message indicates whether the socket close was 
graceful or abortive. If the error code is 0. then the close was graceful; if the error code 
is WSAJECONNRESET, then the socket's virtual socket was reset. This only applies to 
sockets of type SOCK.STREAM. 

The FD_CLOSE message is posted when a close indication is received tor the virtual 
circuit corresponding to the socket. In TCP terms, this means that the FD_ CLOSE is 
posted when the connection goes into the FIN WATT or CLOSE WAIT stales. This 
results from the remote end performing a sfautdownO on the send side or a 
ciosesocketO- 



so 



Please note your application will receive ONLY an FD_CLOSE message to indicate 
closure of a virtual circuit. It will NOT receive an FD_R£AD message to indicate this 
condition. 



Error Codes WSANOTTNTTTALISED 



A successful WSAStartupO must occur before 
using this APL 
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WSAEENVAL 

WSAEINPROGRESS 
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The Windows Sockets implementation has detected 
chat the network subsystem has failed. 

Indicates that one of the specified parameters was 
invalid 

A blocking Windows Sockets operation is in 
progress. 



Additional error codes may be set when an application window receives a message 
This error code i s extr acted from the LP a r am in the reply message using the 
WSAGCTSELECTERKOR macro. Possible error codes for each network event are- 
Event: FD_CONNECT 
Error Porlr 



WSAEADDRJmjSE 
WSAEADDRNOTAVAIL 

WSAEAFNOSUPPORT 

WS AECONNREFUSED 

WSAEDESTADDRREQ 

WSAEFAULT 

WSAEENVAL 

WSAEISCONN 

WSAEMFUJE 

WSA£^^ETUKR£ACH 

WSAENOBUFS 

WSAENOTCONN 

WSAJENOTSOCK 

WSAETTMEDOUT 

Event: FD_CLOSE 

Error Code 

WSAENETDOWN 

WSAECONNRESET 



Meaning 

The specified address is already in use. 

The specified address is not available from the local 
machine. 

Addresses in the specified family cannot be used 
with this socket. 

The attempt to connect was forcefully rejected. 

A destination address is required. 

The namelen argument is incorrect. 

The socket is already bound to an address. 

The socket is already connected. 

No more file descriptors are available. 

The network can't be reached from this host at this 
time. 

No buffer space is available. The socket cannot be 
connected. 

The socket is not connected. 

The descriptor is a file, not a socket. 

Attempt to connect rimed out without establishing a 
connection 

Meaning 



The Windows Sockets implementation has detected 
that the network subsystem has failed. 

The connection was reset by the remote side. 
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WSAECO MN AB ORTED 



The connection was aborted due to timeout or other 
failure. 



w 



Event: FD.READ 
Event: FD_WRITE 
Event: FD_OOB 
Event: FD_ACCEPT 
PjTQr Code 



WSAENETDOWN 



75 



The Windows Sockets implementation has detected 
that the network subsystem has failed. 



20 



25 



Notes For 
Windows Sockets 

Suppliers It is the responsibility of the Windows Sockets Supplier to ensure that messages are 

successfully posted to the application. If a PostM essageO operation fails, the Windows 
Sockets implementation MUST re-post that message as long as the window exists. 

Windows Sockets suppliers should use the WSAMAJCESELECTREPLY macro when 
constructing the IParam in the message. 

When a socket is closed, the Windows Sockets Supplier should purge any messages 
rem ainin g for posting to the application window. However the application must be 
prepared to receive, and discard, any messages which may have been posted prior to the 
closesocketQ. 
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See Also 



selectQ 
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4.3.8 WSACancelAsyncRequest() 

Description Cancel an incomplete asynchronous operation, 
^include <wiasock.b> 

int PASCAL FAR WSACancelAsyncRequest ( HANDLE hAsyncTaskHandle ); 



HAsyncTaskHandle 



Specifies the asynchronous operation to be canceled. 



Remarks The WSACanceLAsyocRequestO function is used to cancel an asynchronous operation 

which was initiated by one of the WSAAsyncGetXBy Y0 functions such as 
WSAAsyncGetHostByNaxneO- "The operation to be canceled is identified by the 
HAsyncTaskHandle parameter, which should be set to the asynchronous t**k handle as 
returned by the initiating function. 



Return Value 



Comments 



The value returned by WSACancelAsyucRequestO is 0 if the operation was 
successfully canceled. Otherwise the value SOCKET„ERROR is returned, and a 
specific error number may be retrieved by calling WSAGetLastErrorO. 

An attempt to cancel an existing asynchronous WSAAayncG etXBy Y0 operation can 
fail with an error code of WSAEAf .READY for two reasons. First, the original 
operation has already completed and the application has dealt with the resultant 
message. Second, the original operation has already completed but die resultant 
message is still waiting La the application window queue. 

Notes For 
Windows Sockets 

Suppliers It is unclear whether the application can usefully distinguish between WSAEINVAL 
and WS AEALREADY. since in both cases the error indicates chat there is no 
asynchronous operation in progress with the indicated handle. [Trivial exception: 0 is 
always an invalid asynchronous task handle.] The Windows Sockets specification does 
not prescribe how a conformant Windows Sockets implementation should distinguish 
between the two cases. For maximum portability, a Windows Sockets application 
should treat the two errors as equivalent 



Error Codes WS ANOTTXTTTALISED 
WSAENETDOWN 
WSAEINVAL 
WSAEEsTROGRESS 
WS AEALREADY 



A successful WSAStartupO must occur before 
using this APL 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

Indicates that the specified asynchronous handle 
was invalid 

A blocking Windows Sockets operation is In 
progress. 

The asynchronous routine being canceled has 
already completed. 
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5 See AJso WSAAsyocGetHoslByAddrO. WSAAsyncCetHostByNameO. 

WSAAsvn'cGetPr.otoByNumberO. WSAAsyncGetProtoByNanieO. 
WSAAsyncGetHostByNamcO. WSAAsyocGetServByPortQ. 
| WSAAsyacGetServByNanieO- 
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4.3.9 WSACancelBIockingCailO 

Description Cance! a blocking call which is currently in progress, 
^include <winsock.h> 
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I int PASCAL FAR WSACancel Block in gCail ( void ); 

Remarks This function cancels any outstanding bloc king operation for this cask. It is normally 

used in two sicuarions: 

(1) An application is processing a message which has been received while a blocking 
call is in progress. In this case. WSAlsBlockingO will be true. 

(2) A blocking call is in progress, and Windows Sockets has called back to the 
applications "blocking hook" function (as established by WSASetBlockingHookO)- 

In each case, the original blocking call will terminate as soon as possible with the error 
WSAEINTR. (In (I), the terminadoa will not take place until Windows message 
scheduling has caused control to revert to the blocking routine In Windows Sockets. In 
(2). the blocking call will be terminated as soon as the blocking hook function 
completes.) 

In the case of a blocking coonectO operation, the Windows Sockets implementation 
will terminate the blocking call as soon as possible, but it may not be possible for the 
socket resources to be released until the con nation has completed (and th **n been reset) 
or timed out. This is likely to be noticeable only if the application immediately tries to 
open a new socket (if no sockets are available), or to coonectO to the same peer. 

Cancelling an accept© or a seiectO call does not adversely impact the sockets passed to 
these calls. Only the particular call fails: any operation that was legal before the cancel 
is legal after the cancel, and the state of the socket is not affected in any way. 

Cancelling any operation other than acceptO and seiectO can leave the socket in an 
indeterminate state. If an application cancels a blocking operation on a socket, the only 
operation that the application can depend on being able to perform on the socket is a 
call to closesocketO. although other operations may work on some Windows Sockets 
implementations. If an application desires maximum portability, it must be careful not 
to depend on perfo rm i ng operations after a cancel. An application may reset the 
connection by setting the timeout on SO_UNGER to 0. 

If a cancel operation compromised the integrity of a SOCK_ST"REAM*s data stream in 
any way. the Windows Sockets implementation must reset the connection and fail all 
future operations other than closesocketO with WSAECONN ABORTED. 

Return Value The value returned by WSACancelBIockingCailO is 0 if the operation was 

successfully canceled. Otherwise the value SOCKET.ERROR is re turned, and a 
specific error number may be retrieved by calling WSAGetLastEnrorO- 

Comments Note that it is possible that the network operation completes before the 

WSACancelBIockingCailO is processed, for example if data is received into the user 
buffer at interrupt time while the application is in a blocking hook. In this case, the 
blocking- operation will return successfully as if WSACancelBIockingCailO had never 
been called. Note that the WSACancelBIockingCailO still succeeds in this case: the 
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oaly way to know with cenaiary thai an opcratioa was actually canceled is to check /or 
a return code of WS AEINTR from the blocking call. 

Error Codes W S AJS r OTTNTTTAL I S ED A successful WSAStartupO muse occur before 

using this API. 

10 WS AENETDOWN The Windows Sockets implementation has detected 

that the network subsystem has failed. 

WSAETNVAI, Indicates that there is ao outstanding blocking call. 
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4.3.10 WSACIeanup() 

Description Terminate use of the Windows Sockets DLL. 
"include <wiosock.h> 
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inl PASCAL FAR WSACIeanup ( void ); 

Remarks An application or DLL is required to perform a (successful) WSAStartupO caJJ before 

it can use Windows Sockets services. When it has completed the use of Windows 
Sockets, the application or DLL must call WSACIeanupO to deregister itself from a 
Windows Sockets implementation and allow the Implementation to free any resources 
allocated on behalf of the application or DLL. Any open SOCX_STR£AM sockets that 
are connected when W SAC lean upO is called are reset; sockets which have been closed 
with closesocketO but which still have pending data to be sent are not affected -the 
pending data is still sent. 

There must be a call to WSACIeanupO for every call to WSAStartupO made by a 
task. Only the final WSACIeanupO for that task does the actual cleanup; the preceding 
calls simply decrement an internal reference count in the Windows Sockets DLL. A 
naive application may ensure that WSACIeanupO was called enough times by calling 
WSACIeanupO in a loop until it returns WSANOTTNTTIALISED. 

Return Value The return value is 0 if the operation was successful Otherwise the value 

SOOCET^ERROR is returned, and a specific error number may be retrieved by calling 
WSAGetLastErrorQ. 

Comments Attempting to call WSACIeanupO from within a blocking hook and then failing to 
check the return code is a common Windows Sockets programming error. If an ., 
application needs to quit while a blocking call is outstanding, the application must first 
cancel the blocking call with WSACancelBlockingCallO then issue the 
WSACIeanupO call once control has been returned to the application. 

Notes For 
Windows Sockets 

Suppliers Weil-behaved Windows Sockets applications will make a WSACIeanupO call to 

indicate de registration from a Windows Sockets implementation. This function can 
thus, for example, be utilized to free up resources allocated to the specific application. 

A Windows Sockets implementation must be prepared to deal with an application 
which terminates without invoking WSACIeanupO - for example, as a result of an 
error. 

In a multithreaded environment. WSACIeanupO terminates Windows Sockets 
operations for all threads. 

A Windows Sockets implementation must ensure that WSACIeanupO leaves things in 
a state in which the application can invoke WSAStartupO to re-establish Windows 
Sockets usage. 



Error Codes WSANOTINmALISED 



A successful WSAStartupO must occur before 
using this APL 
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WSAENFTDOWN 



WSAEINPROGRESS 
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The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 



See Also WSAStartupO 
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4.3.11 WSAGetLastErrorO 

Description Get the error status for the last operation which faiied. 
^include <winsock.h> 

lot PASCAL FAR WSAGetLastError ( void ); 



Remarks 



Return Value 



This function re rums the last network error that occurred. When a particular Windows 
Sockets API function indicates that an error has occurred, this function should be called 
to retrieve the appropriate error code. 

The return value indicates the error code for the last Windows Sockets API routine 
performed by this thread. 



Notes For 
Windows Sockets 

Suppliers The use of the WSAGetLastErrorO function to retrieve the last error code, rather fhan 
relying on a global error variable (cf. errno). is required in order to provide 
compatibility with future muiti- threaded environments. 

Note that in a nonpreemptive Windows environment WSAGetLastErrorO is used to 
retrieve only Windows Sockets API errors. In a preemptive environment. 
WSAGetLastErrorO will invoke GetLastErrorO. which is used to retrieve the error 
status for all Win32 API functions on a per-thread basis. For portability, an application 
should use WSAGetLastErrorO immediately after the Windows Sockets API function 
which failed. 



See Also 



WSASetLastErrorO 
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4.3.12 WSAIsBlockingO 

Description Determine if a blocking call is in progress, 
^include <wiusock.h> 

BOOL PASCAL FAR WSAlsBIocking ( void ); 

Remarks This function allows a task to determine if it is executing while waiting for a previous 

blocking call to complete. 



Return Value The return value is TRUE if there is an outstanding blocking funcdon awaiting 
completion. Otherwise, it is FAI^SE. 

Comments Although a call issued on a blocking socket appears to an application program as 

though it "blocks", the Windows Sockets DLL has to relinquish the processor to allow 
other applications to run. This means that it is possible for the application which issued 
the blocking call to be re-entered, depending on the message(s) it receives. In rhi< 
instance, the WSAIsBlockingO function can be used to ascertain whether the racir has 
been re-entered while waiting for an outstanding blocking call to complete. Note that 
Windows Sockets prohibits more than one outstanding call per thread. 

Notes For 
Windows Sockets 

Suppliers A Windows Sockets implementation must prohibit more than one outstanding blocking 
call per thread. 
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4.3.13 WSASetBIockingHookQ 

Description Establish an appLication-speciflc blocking hook function, 
^include <winsock.h> 

FARPROC PASCAL FAR WSASetBlockingHook ( FARPROC IpBlockFunc ); 



IpBlockfunc A pointer to the procedure instance address of the blocking function to 
be installed. 

Remarks This function installs a new function which a Windows Sockets Implementation should 

use to implement blocking socket function calls. 

A Windows Sockets implementation includes a default mechanism by which blocking 
socket functions are implemented. The function WSASetBlockingHookO gives the 
application the ability to execute its own function at "blocking" time in place of the 
default function. 

When an application invokes a blocking Windows Sockets API opera don. the Windows 
Sockets implementation initiates the operation and then enters a loop which is similar to 
the following pseudocode: 

for(;;) { 

flush messages for good user response */ 
while (BlockingHook ( ) ) 

/• check for WSACanceiaiockingCall () */ 
if (operation_cancelled 0 ) 
* break; 

/• check to see if operation completed */ 
if (operation_campiece () ) 

break; /* normal completion "/ 

. ) 

Note that Windows Sockets implementations may perform the above steps in a different 
order; for example, the check for operation complete may occur before calling the 
blocking hook. The default BlockingHookO function is equivalent to: 

BOOL Default31ocJcingHook (void) { 
MSG mag; 
BOOL ret; 

/* get the next message if any */ 

ret - (BOOL) PeekMessage (imsg, NULL, 0, 0, PM_REMOVE) ; 
/• if we got one, process ic */ 
if (ret) ( 

Trans lateMessage (£msg) ; 

DispatchWessage (4msg) ; 

\ 

/• TRUE if we got a message •/ 
return ret; 

\ 

The WSASetB locking Hook 0 function is provided to support those applications which 
require more complex message processing - for example, those employing the MDf 
(multiple document interface) model. It is 001 intended as a mechanism for performing 
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Return Value 
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general applications functions. In particular, the only Windows Sockets API function 
which may be issued from a custom blocking hook function is 
WSACanceLBIockiagCaJlO. which wiii cause the blocking loop to terminate. 

This function must be implemented on a per-task basis for non-multithreaded versions 
of Windows and on a per- thread basis for multithreaded versions of Windows such as 
Windows NT. It thus provides for a particular task or thread to replace the blocking 
mechanism without affecting other ta^s or threads. 

In multithreaded versions of Windows, there is no default blocking hook-blocking calls 
block the thread that makes the call However, an application may install a specific 
blocking hook by calling WSASetBlockiogHookO- 

Tois allows easy portability of applications that depend on the blocking hook behavior. 

The return value is a pointer to the procedure-instance of the previously installed 
blocking function. The application or library that calls the WSASetBtockingHook 0 
function should save this return value so that it can be restored if necessary. (If 
"nesting" is not important, the application may simply discard the value returned by 
WSASetBlockingHookO and eventually use WSAUnfaookBlockingHookO to restore 
the default mechanism.) If the operation fails, a NULL pointer is returned, and a 
specific error number may be retrieved by calling WSAGetLastErrorQ. 



Error Codes WSANOTTNITIALISED 



WSAENFIDOWN 



35 



See AJso 



WSAHNPROGRESS 



WSAUnhookBlockiogHookO 



A successful WSAStartupO must occur before 
using this APL 

The Windows Sockets implementation has detected 
that the network subsystem has failed. 

A blocking Windows Sockets operation is in 
progress. 
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4.3.1 4 WSASetLastError() 

Description Set the error code which can be retrieved by VVSAGetLastErrorO. 

^include <wiosock.h> 

| void PASCAL FAR WSASetLastError ( int iError ); 

Remarks This function allows an application to set the error code to be returned by a subsequent 

VVSAGetLastErrorO call for the current thread. Note that any subsequent Windows 
Sockets routine called by the application will override the error code as set by this 
routine. 

iError Specifies the error code to be returned by a subsequent 

VVSAGetLastErrorO call. 

Notes Foe 
Windows Sockets 

Suppliers In a Win32 environment, this function will invoice SetLastEnrorO. 

Return Value None. 

Error Codes WSANOTINrriALISED A successful WSAStartupO must occur before 

lining rhig APL 

See Also VVSAGetLastErrorO 
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4.3.15 WSAStartupO 
Description 

^include <wtnsock.b> 

int PASCAL FAR WSAStartup ( WORD wVersionRequested, 
LPWSADATA IpWS.AData ); 



wVersionRequested The highest version of Windows Sockets API support that the 
caller can use. The high order byte specifies the minor 
version (revision) number: the low-order byte specifies the 
major version number. 

IpWSAData A pointer to the WS ADATA data structure that is to receive 

details of the Windows Sockets implementation. 

Remarks This function MUST be the first Windows Sockets function called by an application or 

DLL. It allows an application or DLL to specify the version of Windows Sockets API 
required and to retrieve details of the specific Windows Sockets Implementation. The 
application or DLL may only issue further Windows Sockets API functions after a 
successful WSAStartupO invocation. 

In order to support future Windows Sockets Implementations and applications which 
may have functionality differences from Windows Sockets I.I, a negotiation takes 
place in WSAStartupO- The caller of WSAStartupO and the Windows Sockets DLL 
indicate to each other the highest version that they can support, and each confirms that 
the other's highest version is acceptable. Upon entry to WSAStartupO. the Windows 
Sockets DLL examines the version requested by the application. If this version is 
higher than the lowest version supported by the DLL. the call succeeds and the DLL 
returns in wHighVersion the highest version it supports and in wVersion the minimum 
of its high version and wVersionRcquested. The Windows Sockets DLL then assumes 
that the application will use ^Version. If the ^Version field of the WSADATA 
structure is unacceptable to the caller, it should call WSACleaaupO and either search 
for another Windows Sockets DLL or fail to initialize. 

This negotiation allows both a Windows Sockets DLL and a Windows Sockets 
application to support a range of Windows Sockets versions. An application can 
successfully utilize a Windows Sockets DLL if there is any overlap in the version 
ranges. The following chart gives examples of how WSAStartupO works in 
conjunction with different application and Windows Sockets DLL versions: 
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The following code fragment demonscrates how an application which supports only 
version i.l of Windows Sockets makes a WSAStartupO call: 

WORD wVers ion.Requested; 
W SAD ATA wsdData; 
mt err; 



wVersionRequested = tMAKEWCRD ( 1, 1 ); 

err - WSAStartup ( wVers lonRequesced, SwsaData ); 

if { err 1=0) { 

/* Tell the user that we cculdn't find a useable */ 
/• winsock.dll. •/ 
return; 

\ 

/* Confirm that the Windows Sockets DLL supports 1.1. •/ 
/-.Note that if the DLL supports versions greater */ 
/* than 1.1 in addition to 1.1, it will still return */ 
/• 1.1 m wVersion since that is the version we */ 
/ w requested. */ 

if ( LOBYTE ( waaData .wVersion ) ! - 1 (1 

H IB YTE ( wsaData. wVersion ) != 1 ) { 
/• Tell the user that we couldn't find a useable •/ 
/* winsock.dll. •/ 
WSACleanup ( ) ; 
return; 

} 

/* The windows Sockets DLL is acceptable. Proceed. */ 



And this code fragment demonstrates how a Windows Sockets DLL which supports 
only version 1.1 performs the WSAStartupO negotiation: 

/• Make sure that the version requested is >- 1.1. •/ 
/* The low byte is che major version and the high •/ 
/* byte is the minor version. */ 



if ( LOBYTE ( wVersionRequested ) < 1 It 

( LOBYTE ( wVersionRequested ) — 1 && 
HIBYTE ( wVersionRequested ) < 1 ) { 
return WSAVERNOTS u"P PORTE D ; 

} 

/* Since we only support 1.1, set both wVersion and •/ 
/* wHighVersion to 1.1. »/ 



lpWsaData->wVersion - MAKEWORD ( 1, 1 ); 
lpWsaData->wHighVersion - MAKEWORD ( 1, 1 ); 

Once an application or DLL has made a successful WSAStartupO call, it may proceed 
to make other Windows Sockets API calls as needed. When it has finished using the 
services of the Windows Sockets DLL. the application or DLL must call 
WSACIeanupO in order to allow the Windows Sockets DLL to free any resources for 
the application. 
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Details of the acruai Windows Sockets implementation are described in die WSADaca 
structure defined as follows: 



uc: wSAData { 
"CRD 
WORD 
char 
char 

unsigned shore 
unsigned short 
char FAR * 



} ; 



wHighVersion; 

szDescnpt ion ( WSA3ESCRIPTI0N 1EN+1 ] ; 

s 2 SystemS Cat us ( W'SAS YS3?ATLhS_LEN-r 1 | ; ' 

iMaxSocJcets; 

iMaxUdpDg; 

Ip Vendor rnfo; 



The members of this structure are: 
EkmfiflE Usage 

w Version The version of the Windows Sockets specification that the Windows 

Sockets DLL expects the caller to use. 
wHigh Version The highest version of the Windows Sockets specification that this 

DLL can support (aJso encoded as above). Normally this will be the 

same as ^Version, 

subscription A null- terminated ASCII string into which the Windows Sockets DLL 
copies a description of the Windows Sockets Implementation, 
including vendor identification. The text (up to 256 characters in 
length) may contain any characters, but vendors are cautioned against 
including control and formatting characters: the most likely use that 
an application will put this to is to display it (possibly truncated) in a 
status message. 

szSystemStatus A null -terminated ASCII string into which the Windows Sockets DLL 
copies relevant status or configuration information. The Windows 
Sockets DLL should use this field only if the information might be 
useful to the user or support staff: it should not be considered as an 
extension of the szDcscription Field. 
LMaxSockets The maximum number of sockets which a single process can 

potentially open. A Windows Sockets implementation may provide a 
global pool of sockets for allocation to any process; alternatively it 
may allocate per-process resources for sockets. The number may we LI 
reflect the way in which the Windows Sockets DLL or the networking 
software was configured. Application writers may use this number as 
a crude indication of whether the Windows Sockets implementation is 
usable by the application. For example, an X Windows server might 
check iMaxSockets when first started: if it is less than 8. the 
application would display an error message instructing the user to 
reconfigure the nerw OT king software. (This is a situation in which the 
szSystemStatus text might be used.) Obviously there is no guarantee 
that a particular application can actually allocate iMaxSockecs sockets, 
since there may be other Windows Sockets applications in use. 
iMaxUdpDg The size in bytes of the largest UDP datagram that can be sent or 
received by a Windows Sockets apphcatioo. If the implementation 
imposes no limit, iMaxUdpDg is zero. In many implementations of 
Berkeley sockets, there is an implicit limit of 3 192 bytes on UDP 
datagrams (which are fragmented if necessary). A Windows Sockets 
implementation may impose a limit based, for instance, on the 
allocation of fragment reassembly buffers. The miniu m value of 
iMaxUdpDg for a compliant Windows Sockets implementation is 512. 



120 



EP 0 770 958 A1 



WSAStartup 108 

Mote that regardless of the value of iMaxUdpDg. it is inadvisable co ■ 
attempt co send a broadcast datagram which is larger rhaq the 
Maximum Transmission Unit (MTU) for the network. (The Windows 
Sockets API does not provide a mechanism to discover the \fTL r . but 
it must be no less than 512 bytes.) 
IpVendorln/o A far pointer to a vendor- specific daxa s true tare. The definition of 
this structure (if supplied) is beyond the scope of this specification. 

An application or DLL may call WSAStartupO more than once if it needs to obtain the 
WSAData structure information more than once. However, the *>VersionRequired 
parameter is assumed to be the same oq all calls to WSAStartupO; that is. an 
application or DLL cannot change the version of Windows Sockets it expects after the 
initial call to WSAStartupO. 

There must be one WSACIeanupO call corresponding to every WSAStartupO call to 
allow third-party DLLs to make use of a Windows Sockets DLL on behalf of an 
application This means, for example, that if an application calls WSAStartupO three 
times, it must call WSACIeanupO three times. The first two calls to WSACIeanupO 
do nothing except decrement an internal counter; the final WSACIeanupO call for the 
task does all necessary resource deallocation for the 

Return Value WSAStartupO returns zero if successful Otherwise it returns one of the error codes 
Listed below. Note that the normal mechanism whereby the application calls 
WSAGetLastJErTorO to determine the error code cannot be used, since the Windows 
Sockets DLL may not have established the client data area where the "last error" 
information is stored. 

Notes For 
Windows Sockets 

Suppliers Each Windows Sockets application MUST make a WSAStartupO call before issuing 
any other Windows Sockets API calls. This function can thus be utilized for 
initialization purposes. 

Further issues are discussed in the notes for WSACIeanupO. 

Error Codes WSASYSNOTOEADY Indicates that the underlying network subsystem is 

not ready for network coenmunicadon. 

WSAVERNOTSUPPORTED 

The version of Windows Sockets API support 
requested is not provided by this particular Windows 
Sockets implementation. 

WSAEINVAL The Windows Sockets version specified by the 

application is not supported by this DLL. 

See AJSO sendQ. sendtoQ. WSACIeanupO 
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4.3.16 WSAUnhookBlocklngHook() 
Description Restore the default blocking hook function. 



^include <winsock-h> 



int PASCAL FAJ? WSAUahook Blocking Hook ( void ); 

Remarks This functioa removes any previous blocking hook. thai has been installed and reinstalls 
the default blocking mechanism. 

WSAUnhookBlockingHookO will always install the default mechanism, not the 
previous mechanism. If an application wish to nest blocking hooks - i.e. to establish a 
temporary blocking hook function and then revert to the previous mechanism (whether 
the default or one established by an earlier WSASetBlockiogHookO) * it must save and 
restore the value returned by WSASetBlockingHookO: it cannot use 
WSAUofaookBlockiogHookO. 

In multithreaded versions of Windows such as Windows NT. there is no default 
blocking hook. Calling WSAUahookBIockingHookO disables any blocking hook 
installed by the application and any blocking calls made block the thread which made 
the call. 

Return Value The return value is 0 if the operation was successful Otherwise the value 

SOCKET_ERROR is returned, and a specific error number may be retrieved by r atlin g 
WSAGetLastEnrorO. 



Error Codes WSANOTTNTTIALISED 



A successful WSAStartupO must occur before 
using this API. 



See Also 



WSASetBIockingHookO 



122 



EP 0 770 958 A1 



Appendix Al : Error Codes 110 



Appendix A, Error Codes and Header Files 
A.1 Error Codes 

The following is a list of possible error codes returned by the WSAGetLastErrorO call, along with their 
explanations. The error numbers are consistently set across all Windows Sockets -compliant 
implementations. 
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The first set of defiairioas is present to resolve contentions between standard C error codes which may be 
defined inconsistently between various C compilers. 
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The second set of definitions provides Windows Sockets versions of regular Berlceiey Sockets error 
codes. 

The third set of definitions consists of extended Windows Sockets-specific error codes. 

The fourth set of errors are returned by Windows Sockets getXby YO and WSAAsyncGetXBy YO 
functions, and correspond to the errors which in Berkeley software would be returned in the hjermo 
variable. They correspond to various failures which may be returned by the Domain Name Service. If 
the Windows Sockets impie mentation does not use the DNS. it will use the most appropriate code. In 
general, a Windows Sockets application should interpret WS/VHOST_NOT_FOUND and 
WSANO_DATA as indicating that the key (name, address, etc.) was no< found., while 
WSATRY.AGAIN and WSAJVO_ RECOVERY suggest thai the name service itself is non-operational. 

The error numbers are derived from the winsockJi header file listed in section A.2.2. and are based on 
the fact that Windows Sockets error numbers are computed by adding 10000 to the "normal" Berkeley 
error number. 

Note that this table does not include all of the error codes defined in winsockJi. This is because it 
includes only errors which might reasonably be returned by a Windows Sockets implementation: 
winsockJi. on the other hand, includes a full set of BSD definitions to ensure compatibility with ported 
software. 



124 



EP 0 770 958 A1 



Appendix A2: Header Files 112 



A. 2 Header Files 

A. 2.1 Berkeley Header Files 

A Windows Sockets supplier who provides a development kit to support the development of Windows 
Sockets applications must supply a set of vestigial header files with names that match a number of the 
header files in the Berkeley software distribution. These fdes are provided for source code compatibility 
only, and each consists of three Lines: 

H.'r.4QC _wcnsoc:<a? c_ 
t : n c 1 - d e < w l r.soc* . , K .> 
I end: f 

The header files provided for compatibility are: 

oetdb.h 

arpa/tneLh 

sys/time.h 

sys/sockeLh 

netinet/in.h 

The file winsock.h contains all of the type and structure definitions, constants, macros, and function 
prototypes used by the Windows Sockets specification. An application writer may choose to ignore the 
compatibility headers and include wiasock_h in each source file. 
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10 



15 



A.2.2 Windows Sockets Header File - winsock.h 

The winsock.h header fde includes a number of types and definirions from the standard Windows header 
file windows,h. The windows-h in the Windows 3.0 SDK (Software Developer's Kit) lacks a .4 induce 
guard, so if you need to include windows-h as well as winsock.h. you should define the symbol 
_ENC_WINDOWS before ^including winsock.h. as follows: 
* include <windows . h> 
*defxnc _INC_wiNDOWS 
^include <winsock.h> 
Users of the SDK for Windows 3. 1 and Uter need not do this. 

| A Windows Sockets DLL vendor MUST NOT make any modifications to this header file which could 
• Impact binary compatibility of Windows Sockets applications. The constant values, function parameters 
and re aim codes, and the like must remain consistent across ail Windows Sockets DLL vendors. 

/• WENSOCX.K — i«£ini:t3na :o be used with the WCNSOCX.DLL 

• This header fiLe corresponds ;o version t.L of the Uir.iows Sockets specification. 

• This file includes pares vhLCh are Copyright <c> ;9B2-".?36 Regents 
" of the University of California. All rights reserved. The 

• Berkeley Software LLcar.se Aqreemer.c specifies the terms and 

• cor.di t ton for redisc nbut lor. . 
•/ 

(Lfndef wrNSOCKAPt_ 
I define "WINSOCKAPT^ 

/ ' 

• ?uil in WTNOOWS-H Lf necessary 
30 •/ 

Ufndef _rNC_MtH00WS 
t include <*mdovs.h> 
#endi£ /• CNC WtNOOWS •/ 



20 



25 



35 



• Basic ay st am type definitions, talten from trie 3SD f i Le sys/tyces.h. 

• / 

typedef unsigned enar u_char; 
typedef unsigned shore u_short; 
typedef unsigned in: u_int; 
typedef unsigned long u_^ong; 

/ * 

• The new type Co be used in ail 

40 * instances which refer :o soefcets. 

•/ 

typedef u_mc SOCKET; 
/• 

• Select uses arrays of SOCKETS. These .tiacros x.antpuldte such 

• arrays. TO SETSIZE nay be definec by the user before including 
45 ' this file, but the default here should be >- 64. 

• CAVEAT lMPLIMENTOR and USER: THESE MACROS AND TYPES MUST 3£ 

• INCLUDED tit WINSOCK.H EXACTLY AS SHOWN HERE. 
•/ 

lifndeC FO SETSlZE 
Mefme ro^SETSTZE 64 
•endif /• FD SETSCZE •/ 



50 



55 



typedef struct fd_set [ 

u short fd_count; /• how r.any are SET? •/ 

SOCXET fd^array [FC^SETSZZEI ; /• an array of SOCKZTs •/ 

J fd_set; 

extern tr.t PASCAL FAR WS A70 L s Set ( SOC.KST. fd_sac FA.* •>; 
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I FD_CL?. t::, s«st ) ;o • ^ 

for ( . » D; : < ■ i 5 - _ s ^ : "A? *i (S9:i )->:i_cour.: ; : - - ) . \ 

. : i i i fd_s9t F A3 * > ( s & : ) ; - > f - _ a : : d y ( j \ 

-f-. lo i /. < i lii^jv. TAP. * i (3«:i » - >:d_:oun'.-:; \ 

{ ( f :^se: FA.-. " ) (set ) i ->fd_irray( : ; * \ 

i ffi_i9 r . FA3 • ) ( s«: i i •> fdarray • v 

i * - ; \ 

* \ 

< (M^sec FAR * ) ( s« t m - > !d_cour.t \ 
a:ei<; \ 

I \ 

I \ 

•cecine "D_S=:T(fd, sac) ;o i \ 

l ; <((Cd_set FAR • ) ( set ) > -> fd^cour.t < FO^SETStiE) \ 

( < fc_s« t FA?. • ) ( t ) i -> fd_array ; { < fd_set FAS • ) (sqc) ) - > ffd_so-.-.c - - | - ?d; \ 
► wnile(O) ~ ~ 

Idef'.nt rO_Zr RC ( so - ) ( ( ( :d_set FA* •) (S9t) ) - >fd_caur.cO) 

•derine rO_CSSFT ( Cd, set) WS A="0 Cs Sec ( ( SOCKET ) fd, (fd_set FAR 'laetl 

/ • 

* 3::uciu:« usod l.i selectO call, taken from the 33D file ay s/t Ltr.e . h . 
■/ 

struct c:n«val ( 

Long tv_sec; /• seconds •/ 

i.ong cv_usec; /• ana .m z ro second s •/ 

) ; 
/• 

* Operations on c;.?«vjIs. 

* MB: t Lmercnp does no; work for >- or <-. 
•/ 

•define tim«ri33»t (;vp) ( (;vp) ->;/_a«c II (cvp) ->cv_usec| 

•define t lmercmp ( c/p, uvp, cmp> \ 

( (cvp)->cv_sec crtp (uvp) ->:v_sec It \ 
(cvp]->c'/_j«c ( uvp ) - >:v^aec •* (tvp)->cv_usec cmp (uvp) ->cv_jj«o 
•define t imerclear { t vp) < t vp) - > c v_sec ■ (tvpj ->tv_usoc - o 

* Commands Cor loct Isocket ( ) # taken from the BSO file fcntl.h. 

* Cacti's have the command encoded in the lower word, 

" and the size of any in or ou: parameters in che upper 

* word. The high 2 bits of :.m upper word are used 

" to encode the in/out status of the parameter; for now 

* we restrict parameters to at most '.23 bytes. 
•/ 

•define COCP AP.MMASK 0x7f /• parameters must be < L29 bytes •/ 

•define IOC_VOIO 0x2CGCQOO0 /* no parameters */ 

•define COC^OUT 0x40000000 /• copy out parameters "/ 

•define [OC_IN 0x33000000 /- copy in parameters •/ 

•define IOC~INOUT ( IOC_ CN* I COC_OOT) 

/* 0x20000000 distinguishes new 4 
old locc 1 * s • / 

•define _CO(x,y) { {OC_vo : D I ( x< <a ) I y ) 

•define _COR<x,y, z ) ( ICC_CU7 I ( < (Long > s i leo f < t ) * tOCPARtt_MASK><< 1 6) I lx<<3l ly> 

• define _tOW<x, y, t) (IOC_iNI ( ( (lonqlaiieoHtl ( rOCPA*« J-ASK )« 1 6 ) I (x<<8) ly) 

• define FIOMRSAO _lO?.l'f. L 2 7, u_long> /• ;ac I bytes to read "/ 

• define FION8IO _ZCW( , f, 125, u_iong) /• set/clear ncn -b lock : nq 1/0 •/ 

• define F Z OAS Tf NC _:cwcf, L25, u_long) /* sec/clear async 1/0 •/ 

/' Socket I/O ConcroLs •/ 

• define 5 IOCSK IWAT .iO'^rr, 0, u_lonq> /• sec nigh watermark -/ 

• define sroCChTrfAT ^tQZi's', l * u~lonq) /• gee high watermark •/ 

• define 5 IOCS LOWAT ^lOWt's', 2, u_long) /• sec low watermark •/ 
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-.9 J . . 
"5 j ! ! 



TSL-WA? 

:A:r.i..-.:< 



'::?.( * : 



it coo ur.<.' "/ 



j-. ::»s r**.j:.-.«: z-y :.9'.--or< cd'.d 3 a s «? Library. :<i/.'jn ' rom \ r. e 

5i3 -*--b..-. . ALL h :^:«5S*3 *r* supplied i .-. hose order, -ir.d 

r 9 - - r r. 9 s in .-4:o;.< ;::o: (suita'a^ for i s e . n s y s : em -alls). 



strict hoi;«n: { 

cr.i: F AS • n ; /• ofJi-rul n i.ne of hose " / 

c.-.ar "A3 • TAR • n_aliises; /• alias list •/ 

snort h_addrcype; /* host address : ype •/ 

s.-or: r._L9ngth; /" Length of address •/ 

:r.ar • AS * FAR * h_add r_l i at ; / * List of jddressas */ 

rdef '.ne r._ idd r h_addr L s c ; 0 | /* addr«as, :o: bac<-ward ccmpac 

» ; 



• Cc ii assumed here that a ne'.-worlt nu.-nbar 

• fits in 32 bus. 
•/ 

s:ruc: necar.t { 

cr.ir FAR • rt_najne; /• official nam* of 

char TAR • FAR " .n_aliases; /* alias list •/ 

shor; n_addrtype; /• net address 1 ype 

•j_ Long n_r.ee ; / • n»two rfc » " / 

) ; 



servant ( 

char FA.R • s_r.a.T.e; 

chdr c A£ ' FAR " s_< 

short s_port; 

char FAJt • 3_?roco; 



/• official service name •/ 

/* alLaa list • / 

/* port # •/ 

/• prococol to use */ 



"pro:oent { 
chac FAX • p_rta."ne; 

char FAS • FAJl * p_al uaea, 
sho:: p_proto; 



/• official protocol na/ne 
/• alias list */ 
/• prococol t '/ 



* Constants and structures defmed by the internet system, 

♦ Per RFC 790, September 1981, talcen from the 3S0 file net l r.e c/ m - h . 
•/ 



* Protocols 



#de fine 


C?PROTO_t? 


0 


/• 


dummy for CP */ 


fdeCine 


EPPROTO~£C«P 


I 


/ • 


concroL message protocol */ 


IdeCir.e 


I?PR0TO~CC? 


2 


/ ' 


cateway*2 (deprecated) */ 


*d«fir.« 


tPPROTO TCP 


6 


/ • 


tcp •/ 


Idefi.-.e 


LPPROTO PUP 


12 


/ • 


pu? •/ 


•define 


tpproto aop 


17 


/ • 


user datagram pro Local */ 


Ice f 1 ne 


I ?P ROTO - : DP 


22 


/ • 


xns idp •/ 


td«5ir.e 


:??ROTC_ND 


77 


/ * 


UNOFFICIAL net dis*. proto V 


tea f 1 r.e 


EPPROTG_RAW 


253 


/ • 


raw IP packet •/ 


Ida f ire 


IPPROTC MAX 


256 







/ • 

• Poct/socKet numbers: recworx standard functions 



idaCint 


CPPORT 


_ECH0 


7 


Mafir.o 


CPPORT 


~C ISCAilO 


9 


»def ine 


CPPORT 


SYSTAT 


11 


#de f t rte 


CPPORT 


"daytime 


13 


»dof ine 


"lPPORT" 


"nxtstat 


L5 


»de f 1 ne 


r??o?.T FTP 


21 


f da f 1 ne 


;?port_telnet 


23 


>de f l ne 


:?port~smtp 


25 


Ida f 1 na 


:pport 


_T rM£S£RV£R 


37 


»daf ine 


:?port' 


~NAME SERVER 


42 
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i ? ?i 

- O 3." 



M7? 



?o r t .* 5 ) : 



>e:j: 



10 



fdefine :??C?.T TTT? 

•define C??ORT~aJE 

•define :??o?.r"r:sc£p. 

ia«f:r.e : ?PCR? ~TT Y 1 : N'K 

•define :??OF.T~3C:?OU? 



• ? 
9 T 

95 



J5 



'jn:x 



Z? soc'n»ts 



• defi.-.e I ? ?0? T El.XZ'IS £ ?.Vt R 5 L 2 

•define :?PORT_LOC:NSZ?.ViR 5l3 

•define :??0RT_CM0S£R7£R 5 14 

»de Cine iPPORT £F3 3 E S20 



20 



• UN EX uDP sockets 
"/ 

•define r??ORT BtFF-VC? 5 12 

•define 1 ? ?ORT~WHOSERVER 5LJ 
►define [??0R7 RO^JTI SERVER 5 20 



/ * 5 20- 1 also usee 



25 



Porta < r?PORT_R£S£Rvio are reserved for 
privileged processes (e.g. root). 



• define) IPPCR7 R£5iRVTD 



10 24 



30 



* Link numbers 

* / 

•define :kpl:.vk_ep 

•define ZMPLINK_LCWEX?ER 

I define EM? LINK HECH£X?1R 



;55 

L53 



'nternet adcress (old style.. 



should be updated) 



35 



40 



45 



50 



struct m_addr ( 
union { 

scrucc ( u_chir s_bl. s_P2, s_b3, s_b4 ; ) S_ur._b; 
scrucc { u_aho rt. 3_-* L , a_*2 , \ S_un_w; 
u_lor.g S_addr ; 

• S_ur.; 

•define s_*ddr S_un.S_addr 

~ /- can be used for .nose ccp * t? code 

•define s — host S_un.5_un_b.s_b2 

/ * hose on i.T.p * / 

•define s_net S_ un - S_un_b . s_b t 

~ ~* /• network "/ 

•define s imp S ur. . S un w.j_w2 

/ • imp */ 

•define s_ixpno S_ur. . S_un_b . s_b4 

~ _ - - / . tmp | * / 

• define s_Lh S_un . S_-jr._b . s_b 3 

~ ~ "" /• logical hose * / 

\ ; 
/ ■ 

• Oefinicions of bits in incernet address integers. 

" Cn subnets, cr.e decomposition of addresses to host and net parts 

• is done according to subnec nasfc, not the masks nere. 



• define EN CLASSAd) 
•define EN~CLASSA_tJET 

• define EN~CLAS3A~"nSH ITT 
•define CN~CLAS S A~H0ST 
•define EN~CLA53 A~MAX 



f((long)(i) i 0x80000000) 0) 
Oxf fOOOCOO 
24 

OxOOf f f f f f 
129 



55 
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'-a:.** :s_"_AiS3 < i i ; r.;r.7i o * :< c c » *> : x 30 : •: ; 

• i i - a I N'_7.LA3 J 3_SI? : : : : Z iC Z 

i -i * i ; n -a : M ~C *_ A 3 i 3 ^ *C $ 7 0 .< 1 0 C 0 J 5 i f 

• ief..-.* Z 3 5~y-AX S 3 5 2 -9 

»d I IAS i C ( . ? » ( ( Icr.a) f ; > ; ; .x c C J - 0 3 0 0 ) »■ OxrOOCCOO 

• d * : : r. e ;m_7,1Aj JC_N£7 Oxrff^f^CO 
*cef:r.e :n_C1A5 5c"n5H lF7 3 

• def:r.9 : N~CLAiSC~HC37 OxJCCOCOff 

•defi-» :naoor_any fu_Lonc;) :<cc:::oco 

•define C N'ADO?. ~ IOC P SACK Cxi fOOOCCl 

•define C SAD0R~5* C ACCAS T ( Lor.? ) 0 x £ * £ 1 f f f * 

# define CNAOOR~NCNE Oxffftffff 

/ ' 

* Soc<ac address, :.*c«:?.«; s-yle, 

• / 

s::uc: soci r .ai;r_in ( 

shore s in_fami iy ; 
u_shar: s i n_po rt ; 
s*r ; jc: i n_addr a ;n_addr; 
char a in zero.; 6! ; 



•define WSAJI5CR :?TION_LHN 23S 
•define WSA5*S_S7AT'JS_L£N 123 

typeeef struct WSAData i 
WORD 
WORD 
char 
Ch a c 

unsigned shore 
unsigrttd short 
cr.ar TAR * 
> WSA0A7A; 

typedef WSACA7A -A-R "LPWSA0A7A; 



• Options for us* w^ch [ga ! etaockopt at the tp level . 
• de £ l n« r?_OPTI0S5 L /• aet/oet CP pec-packet options 



" Oefir.itiona related to sockets: types, address families, options, 
• taken Crom the BSD fiLe sys/socxet - h . 



wv«rs ron; 
vHi?h Vers ion; 

st0escriptior.[W3A0E3CRr?TI0N L£N* 1 1 ; 
szSyscenStatua (WSASYS_STAT r J3"L£N*l | ; 
LMaxSockets; "~ 
iMaxUdpDg; 
laVerdorl.i.'o; 



/ • 

• This is used mstead of -1, sir.ee t*e 

• SOCKZT type is unsigned. 
•/ 

•define r NVAL 1 0 SOCKXT < SOC:<Z7> ( -0 ) 
• define SOCKET ERAOR (-U 



.ypes 



•define SOCK_3TR£AM L 

•define SOCX~CCRAM 2 

• def tne SOCK^RAW 3 

• defi -e SOCK~*CM 4 

• define SOCK SEQPACKXT 5 



/• streajn socket */ 

/■ dataqran socket ■/ 

/ • raw- protocol mte rfaca */ 

/• reliably-delivered message 

/ * sequenced packet st ream • / 



Option fLaga per-socJcet. 



•define SQ_2Z3VG 3x0001 

• define SO_ACC£PTCO.VN 0x0002 

•define SO_R£USEA00R 0x0004 

•define SO_X££?AL I VT 0x0008 

•define SO CCNTROUTS 0x0010 



/• turn on debugging info recordi 

/ * socket has had listen ( ) ♦/ 

/ " allow local address reuse •/ 

/• keep connections alive */ 

/* just use interface addresses •/ 
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:c3:s: 



" < 2 r h 3 

:.<-:ioc 



= 9 r^t ; c 5-*: 
= v p -d s s r. a : 



: i " o : :rriC:ij: r. s z s 
: J -i r ^r. •* r. ?o i i : o L e * / 
ilsse ,t da*, a present ■ 



'. »dv*j receiver 



::a da-* 



1 



;.-.t ) i-SO 



Aad : t :c n a i options. 



tea : 

»d» f :r.e 



30_S NC BUT Ox 10 -I 

30~?.cv3c;r < 1 0 c 2 

• cefir.e 5C~5N0LOWAT OxlOC-3 

•ceCine Sc'p.CVLOWAT 0xlCC4 

•cefine 3C~3S0T:m£O Ox IOCS 

»ce C : ne 50~I?.ROR 0x100 7 

»ce i :r.e SO TYPE Ox ".003 



ser.l buffer ai:o */ 
r<3C9t.va ou!ier si:q */ 
s 9. ".e low'wacar mark */ 
receive law--wd:sr .nacX 
ser.c c -.rrieout • 
:«car.'« ::.?.«0'j: */ 
•;et error scat -a dnd -! 
<7et socitec type */ 



»C«f:a« TCP MOCELAY 



;xoooi 



* Aclress families. 








*/ 

•define AT_CN*S?£C 


0 


/ • 


unspecified * / 


•define ATJJN £X 


1^ 


/ • 


Local co r.oac (pipes, por:alsi */ 


• defir.e Ax~:s'£T 


2 


/ • 


meg mat work. : UDP, TC?,, etc. •/ 


• defir.e AF~:KPLINK 


3 


/ * 


arpanet Lmp addresses */ 


»d« f A"2?U? 


A 


/ • 


pup protocols: e . q . 8SP •/ 


•defir.e AfjCHAOS 


5 


/• 


.nit CfiACS protocols •/ 


•defL-e A"~NS 


5 


/• 


XZROX NS protocols •/ 


•define af~iso 


7 


/ - 


ISO p rococo Ls */ 


•define 9&-~as-t 


AT 130 


/• 


osr is :so •/ 


•define Af~ECMA 


9 


/ • 


European computer maau faccurer s */ 


•define a.-_oatak:t 


9 


/* 


data/tit prococols "/ 


•define A.-~CC:TT 


10 


/• 


CCITT prococols, X.25 etc •/ 


•define AF_SNA 


LI 


/* 


C5M SNA •/ 


•define A5"_0ECnet 


-2 


/ * 


CECnet •/ 


• define Ar_0LI 


.3 


/ • 


Direct data 1 ink. interface •/ 


•define A7 LAT 


14 


/• 


-AT • / 


♦define AT HYL INK 


:s 


/ • 


NSC HyperchanneL "/ 


• define Ai^APPLETAiX 


:6 


/ • 


AppleTaU •/ 


•define Af~>fETB:CS 


v 7 


/ ■ 


Net3ios-styie addresses * / 


• define A_T_MAX 


1a 






/ ■ 

• St ruccure used by 


kerne! co score 


most 





* addresses. 

*/ 

struct sockaddr { 

unshoe: sa_fajnily; /• address family •/ 

cftac sa - dac*|l4| ; /• up =0 14 bytes of direct address */ 

) ; 



/ • 

* Structure used by icerr.el to pass protocol 

• information in raw sockets. 
*/ 

struct sockp:o:o i 

u_shor: sp_fanily; /* address 'amiLy 

u_sh.ort sp_protocol; /■ protocol */ 



* Protocol fa/mlies, saute as address families far' now. 
•/ 

•define pr_UNS?£C Af USSPEC 

•defir.e PF_CJNCX Ai-'USTX 

•defi-e pr^TNET Af_:y£T 

• defir.e ?r":MPL£yX AT_ C>f? L TNK 

•defi-e ?f~?UP AT_PC? 
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* f : 




? T n 3 




-a 


?r": 22 


»=«f: 


-« 


?r~:s: 


i ;e : ; 






i -ZQi: 




?-2-ata:<:t 


M»f: 


-9 




rcafi 


.*■« 




reef. 


.-.a 


pr ^ECnec 


leaf: 


*e 


pf'ol: 


leaf ; 


-a 


PF~LA7 




~e 






-e 


?r~APPL£TA! 




-e 


?" MAX 



A r ~ S 3 

Ar ~Q5 : 

A? ~2 A tax:? 
at'ccitt 

Ar^aNA 

AF~LAT 
AF~HYi:>JK 
AF~APP LETALX 

AF_t-AX 

/ • 

" £ c ruc'.ura used foe ma.-, ipuiit: nq Li.-.qer opc :o;. . 

* / 

s-.ruc: 1 : nqe r ( 

u_sho r t L_3r.off; /* opcicn on/off •/ 

u_5horc 1 — Lir.qar; /* lir.gar •/ 

} ; 
/ • 

* Laval number foe (qec /sac ) socXopc ( I co apply Co soefcee lcaeif. 
•/ 

♦define 3OL_30CXZT Oxfffff * opc.onj Cor sockq: level •/ 

/ • 

* Maximum quoua lengch specifiable by Uitan, 
•/ 

»de>C;n« SOMAXCOVN 5 

♦define MSC_0O9 0x1 /■ proctaj ouc-of-band dacd */ 

♦define MSC_?£EX 0x2 /• peex, ac incoming nsssjqs • / 

♦define MSC_0OSTROEJT£ Cx4 /• j«nd wuhoi:: using routing tables 

»defi.i« MSC_MAX:OVLcN 16 

/ * 

* Define cor.s.anc based on rfc383, used by getnos c Dy xxxx ( } calls. 
•/ 

♦define fr-JUCCETHCSTSTRCJCT :0 2 4 
/ • 

* Oefir.e flags co be used wLCh the WSAAsyncSe lac. { > call. 
*/ 

♦define FD_R£A0 0x01 

♦ da f t r. a 70 wr £TE CxC2 
♦define ?D~0Ca Cx0 4 
Jdefi-t -D~ACCEPT CxOB 
•define FD CONNECT 3x10 

• defi.-e F0~CLOSE 0x20 

/ * 

* Ail Windows SoclcftCa error constants ace biased by "SASAStERR from 

* the * normal " 
*/ 

♦define WSA3ASEERR 13000 
/ • 

* Windows Sockets def:nit;onj of regular Microsoft C error conscancs 

* / 

♦ da Cine WSAE INTR < WS ABASE ER.Ri- 4 ) 
♦define WSAE3A0F <WSABASE£P*R *■ 9 > 
♦define WSAXACCES (W3A8ASEERA* L 3 ) 
Ida fine WSAEFAULT ( wSABASEtPJ** I 4 ) 
• define WSAZINVAL (WSA3ASEZ?J**-22) 
•define WSAEMF t LZ ( WSA3A5EEPJI-*- 2 4 > 

/ • 

* Windows SocXocs definitions of regular 3erkeley error constants 
•/ 

Ida Cine WSAXWOUL3 3L0CK <wSA3AS£S?.R<-35 J 

• da fine WSA£ I NPROGRXS S (WSA9A5E£aR~ 3 6 > 
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» 1 o 




( W 3 A 3 A 3 £ £ ?. ? • 2 ? > 




w 3 A £ >.'C 7 3 T C X 


( W3 A 8 AS ££.-.? - 2 3 > 


* 1 9 ; : - * 


W5 A£-£37A3CA?.££ 


( V3 A 3 A 3 £ £ ?.?. - 3 3 i 




W3A£M5C5 Ct- 


{ WSA5A5" r3:.jfl) 


* 1 <* f 1 * 9 


WSAE? 3.07C7Y ?E 






WJ A£?i-~ ?R*^7TT?7 


(WSA515??3: -J ? 1 
l n <*'^9nJ s b r.. . •* £ 1 


* : 9 i ; " a 




( VV3 A3 A3 E£3?. - « 2 J 




■j ^ * t - v~" *Ji"^ ;;:33-*s" 


(W?i5is?r3 3 . ■ J » 
V "J^wMJC. — ~. -* / 


1^* * .* 
c« . : r.a 


* J s> w r r^<J . jLrr 


i «<;i sierras _ j «. i 


* >i e *. « r. 9 


\j - « r 3 ~ v 'ft ifosr,2^ 
«0«i« ; .<wJUr rv— ■ K . 




'C9 f 1 "9 


njrMrtf Hv jUr r Jr. . 




! i "a 


vj c * ~ « *»■ r* O " v/7 icr 
"JftiAbLIK .NUic 




' C 6 £ I "ft 


■ rinno *Jrt*~ ivi * r 

« 3 « CaUUK.*U . A v A . L 


* JC131 CCDS . J ai 


• C 9 f 1 " • 


vj r « vr 5" t"" itjvl 
^ J «. — — fwO"N 




t-io f i r.9 


* j c * ^ ^ ^ft * iO A ^~ LI 


/ "J C A Q \ c r r 3 5 *_< 1 t 


i** a * * "a 


ye i rwc?3f?rT 


l "jABnj LLR/ ♦ j * J 






rJ<lftA(» F33» \ "l t 


» do C i.-.e 


WSAZCONNAESET 


( WSABAS££RA*5 4 ) 


*de f i *e 


W5A£ ROBOTS 


( WS ABASEERil* 5 5 ) 


Ide f i e 


W5AXCSC0NN 


( W5A9AS££RR>5 6) 


ide 


WSAiNOTCONN 


{WSA3ASE£RS*5 7) 


M9;:n« 


W3A£5:-: f JTDOWN 


tWSA3A5££RJl^Sa) 


»def i.^e 


W3A£TOCrtANYR£="5 


( WS ABA5 ttltJl* 5 9 » 


»<Jof L.H 


W5A£TIM£30'JT 


{ WS ABASE £?,£•♦■ $0 ) 


»de 5 1 no 


WSA£CONNASr%JS£D 


t WSABA5££?J^4- 6 I ) 


»de :ir.« 


WSAX^OO? 


(WSABA5E£R?.<-6 2> 


f da f 


WSA£NAM£T0OL0NC 


tWSABASE£?J».*63) 


Ida f me 


WSAXHOSTOOWN 


(WSAaASEE?JH>5 4) 


Idad.na 


WSAEHOSTCNP.EACH 


(WSABAS£E.:Lq^65> 


Ide f in« 


WSA£NCT EMPTY 


{WSABASEE.^-6 5) 


(d«£:n« 


wsaeprcclim 


(WSABAS££ajl*-5 7) 


Ida fine 


WSAZUSERS 


(WSABAS££RAi-68) 


Ide f i ne 


WSA£CCUCT 


(WSA3A5££RJUo9> 


Ide f i no 


WS*A£STAL£ 




Idef me 


WSA£a£>tOT£ 


(WSA3AS££AA*-7L) 


/ • 

* extended Windows Sockets 


error conscanc de'tn. 


»def:r.e 


WSA5 rS NOT R£ A D f 


(WSAaAS££rLR-9'.) 


(define 


WSAV£RMO7SUPPOR7£0 


(^SABASE£R.R*92) 


f d« f me 


wsanotvn:t:al:3£3 


(WSABAS£ERR+93) 



/ • 

* £rror recurn codas from g<s c host by nana ( ) ana gechos t byaddr ( ) 

* <wh«n using ch« resolve:} . Noce chax close errors are 

" retrieved via WSACecLaacEr ror ( ) and rauat therefora follow 

* :he rules for avoiding clashes with error numbers from 

* specific implementations or language run -time systems. 

" Tor reason the codes are based at WSABAS££=5*- 100 1 . 

* Note also that ( WSA | NO_A0 ORE S3 is defined only for 

* corr.pd z ib 1 1 1 C y purposes. 
•/ 



tdefme h_errr.o wsACe t Cast Error O 

/■ Autfto r i z at l ve Answer: Hose not found •/ 

• define W3AHOST_>fOT_rOUNO ( WSABASEEaR* L 00 I > 

• der^ne HCST_SOT_r0UNQ W5 A.4OST_N0T_rGUN0 

/* Nor. -Author L"a: lva : .Host r.oz found, or SSRVERf A I L 
Idefme WSATR Y_ACAI S (W3ASAS££?J»* L00 2 ) 

#defme T3Y_ACA £S W3ATSY_ACACN 

/ ■ Won recoverable errors. FORKED, RZrusZO, NOT I!-? 
Idefme WSANO_R£COVtRr ( WSA3ASEERJI- LOO J ) 

•define NO_R£CCV£RY WSANO_a£C0VXRY 

/ " Valid nane, no data record of requested type "/ 
Ida fine WSANO_0A7A ( WSABAS££RH- 1 004 ) 

•define M0 — 0A7A WSANC_0ATA 

/• no address, look for MX record */ 

ide fine WSANO_A00R£SS W3ANO DATA 

fdefme NO A00RZSS WS ANO*A00»£SS 
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'"'■.*-:«'3 jc:.<6".3 errors r f : r.*d *s r -s^ 



3* r *. <» L 9 v <i c :o : co.-.;ci r. z s 



• de i : r. 9 I wot-" -33 LOCK 
»daf:r« I ! S??.:CR£33 
fee £ ir.« :a:?.£AwY 

i.s'CTS-OCK 
rdel;r.e ECESTADORRZC 
»defi-9 EMSCSTIE 
>d*f;-« EPRC707YPE 
•d»f:r* ENOPROTOOPT 

• define) E?ROTONOSU?PO=.T 
»d»f:.i9 ESCCKTNOSL'PPOST 
fiof:.ie EOPNG7SUPP 
»defi.-.« EPFNOSUPPCRT 
Ids Cine EI AT NO SUPPORT 
Ideftr.a EADOR INUS £ 
rdafme EA0ORNOTAVA 1 1 
•define ENETDOWN 
fcaCi.-.e ENETUNREACH 
#d*f:.r.e ENTTRE5ET 
fda!:r.9 ECONNA30RTED 
»d«.'.a« SCONNRESET 
fdaJi.ie ENOSUrS 
»d«::r.« EtSCOMK 
»d«fme ENOTCCN'N 
»d«fine ESHUTCCWN 
Idefine ETOOMANYREFS 
f4«fine ET tMEOOUT 
#<l«fin« ECONXREFUSED 
♦define ELOOP 

»d«f :n« ENAMETOOLOtfC 
»d*fin* Z HOST DOWN 
»d«Cine EHOSTUNREACH 
♦define ENCT EMPTY 
#d#ftr.« EPROCLtM 
fdeffir.e EUSERS 
»d9fir.a E0QUOT 
rdefL-e ESTALE 
>d ft fine SREMOTE 



W3AEWC-JL2 3LOCSC 

W2AEiN??CCREi3 

W3AEALRSACY 

WSAE NOT SOCK 

W3AE3E3TA0C?A£Q 

WSAEMSCS C2E 

W3 A- PROTOTYPE 

WSAENCPROTOOPT 

WSAEPRCTONOS'JPPCRT 

WSAESCCKTNOS-UPPCRT 

W3AXCPNOTSCJP? 

W3AEPFNOSUPP0RT 

W3AEAFNOSUPPORT 

WSA£AD0RINySE 

WSAEADDRNOTAVA I L 

WSAXMETOOWN 

WSAE>*ETUNREACH 

WSAENETRE5ET 

WSAECONNA30RTSD 

WSAECONMRESET 

WSAENOBUFS 

WSAETSCONN 

WSA£NOTCOS-N 

WSAESHUTCCWN 

WS AETOOMANYREFS 

WSAETIMECOUT 

WSAECONNREFUSEO 

WSAELOOP 

WSAENAMETOOLONC 

WSA£HOSTDOWN 

WSAEHOSTUNREACH 

WSAXNCTEMPTY 

WSAEPROCLIM 

WSAEUSERS 

W3AE0Q0OT 
WSAZS7ALE 
WSAE REMOTE 



/ * Socket function prototypes * / 



lifdef cpluspius 

extern *C * ( 
»endi r 



SOCKET PASCAL FAK accept (SOCKET a, struct soefcaddc FAR *addr. 

inc FAR 'adcclen) ; 

int PASCAL TAR bind (SOCKET J, const struct socnaddr FAR 'addr, inc r.anteien) ; 
in: PASCAL FAR clos«soclc«c ( SOCKET s); 

int PASCAL FAR connect (SOCKET a, const struct soefcaddr FAR •name, inc nameLo.'w; 

int PASCAL FAR :oct lsocicet ( SOCKET s, ;oncj cxd, u_lonc- FAR *ar<7p> ; 

int PASCAL FAR qacp»«r.-.arn« (SOCKET s, scruct soclcaddr FAR *na/ne, 

mt FAR • namelent ; 

inc PASCAL FAR gee soc:<narte (SOCKET s, strucc sockaddr FAR *na.Tie, 

i.-.t FAR • na.naUn) ; 

u: PASCAL FAR getsoefcope (SOCKET s, inc Level, mt optnaro*, 

cr.ar FAR " optvai, ir.z FAR •opclen); 

u^Lonq PASCAL FAR htonl (u_Long hostlonq); 

u_*horc PASCAL FAR htons (u_short hostshort); 

unsigned long PASCAL FAR mec_addr (const char FAR * cp); 

char FAR • PASCAL FAR ir,ec_ncoa (struct m_addr in); 
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. -". .- - L . r A ?. : s - <a i:-::k.iT 5, mc :j:<> j ) ; 
- _ . j ." i ? A i CA 1 r A ?. r.zcn. ( j_!cr..-7 *<3i ior- ) ; 
- _ i - ; : * ? A J ~A L ~ A ?. - 1 jr. s ( :_s>.o:: a'.sr.o:: i ; 

: r. : PASCAL "A? recv ( 5 >^:<IT s , :air FAR • buf, . e - . ; - : fli.;j: ; 

PASCAL FAR recvfrom (SOCKET s, c'.d: FAR " S<j f , :.ic Un, : ni flags, 
s : rue: soc<<Jdd: FAR 'from, •. -: * FAS • ! :o.n . <a n i ; 

Imt PASCAL FAR solflc: ( : r. : nfds. fdsec FAR Toadies, !d_set FAR •wriruids, 
:j_3gc FAJl 'except fd3, :ons: struct :u«vil FAR ':;(neou:); 

| mz PASCAL FAR send :SOCK£T 3, const char FAR • bur", mc Lan, ; nc J lacs); 

I.,: PASCAL FAR send to ( 3 OC X£ T s, const Char FAR • buf, mc Len, i.-.c flags, 
:oaa: at: 1 ::: sockacdr FAR *tc, ;n: colon); 

mc PASCAL FAR setsocico?: tSOCKZT s, mc L»v«;, :nc optname, 
(• const char FAR " optval, l n* opc ier.) ; 

ir. PASCAL FAR shutdown t SOCKET s, int how); 

SOC'fUT PASCAL FAR socket ( i nc af, me type, mc prococol); 

/• database function prototypes •/ 

scruc: hoscenc FAR • PASCAL FAR gechostbyadd r ( cons; chac FAR * addr. 

me lan, mc type); 

struct hoscenc FAR • PASCAL FAJl gethostbyname ( consc char FAJl • na/ne); 

mi PASCAL FAR gechosc-ane Icha: FAR • nans, mc namelen) ; 

struct sarvenc FAR • PASCAL FAR q*c se rvbypo rt ( i r.c poet, consc char FAR • proco); 

scrucc sarvenc FAR " PASCAL FAR gee sa rvbynajne ( consc char FAR • nana, 

cor.se char FAJl • proco); 

struct pcoccenc FAJl * PASCAL FAR qec proeoby nitube r Unt proco); 

struct pcocoenc FAJl • PASCAL FAR gecproc obyna-Tte {const char FAR • name); 

/" Microsoft Windows Extension function prototypes •/ 

mt PASCAL FAR WSAS ta rtup ( WORD wV«r s lonftequi red. LP WS AO ATA IpWSAOaca); 

mc PASCAL FAR WSACl eanup ( vo id ) ; 

void PASCAL FAR WSASecLastError ( mc lError); 

mc PASCAL FAR WSAGecLa scE r ror ( void) ; 

BOOL PASCAL FAR MSAIsaiockmq ( void) ; 

ins PASCAL FAR WSAUntiooAaLocfcingHooit { vo id ) ; 

FAR»ROC PASCAL FAR wSAS«c31oc<mqHoaX (FARPROC 1 pB loekTunc ) ; 
mc PASCAL FAR W5 AC a nee I 3 LocK mgCa 1 1 f vo id) ; 

HA NO L£ PASCAL FAR WSAAs y-=CaC Se rveyNane (HWNO r.Wnd, u mc wfisg. 

consc char FAR * name, 
consc char FAR • proco, 
cnar FAR • buf, mc buflenj; 

KANC1E PASCAL FAR WSAAsyncGe t Se cvByPo re (HWNO h«nd. J_inc Jj-sq, t.-.t port, 

consc c. L .ac FAR * proco, char FAR * buf, 
mt buf I en) ; 

KANOLE PASCAL FAR WSAAsy.ncCacProcoByNa.Tie (HWNO hWnd, « mc ^Msg, 

const c.-.ar FAR • r.a.-ne, char FAR • buf, 
i r.c bu C 1 an) ; 
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.- \r.2ll ? A J ZA L "A?. W £ AA s y - cC * t ? r J : - 3 y S J.r.oe r ( H WNS - * nd . u_ i r. '. w.M s c . 

. nc -:.rr.r« r, j. w . i r FAR * 3*: : , 
in: o j f 1 *i r. ) ; 

r.X'.'.Zlt ?AJ*AL "A?. *JAAsyn ;Cet Hos t SyNasie t HWND .-.Wr.c, 
I ;5.-s: :har FA A • -aise, -mar TAP. * ojf." 

_buf ; 

r..\SZLZ PAiCAl FAR * : AA J y - -Ce : Ho 5 t 3 y Ada r ( HWNC r.Wnd, n_L.it "-Ms^, 

cor.s; char FAR • ace r , 
cans; c^a: FAR * buf, 

:.it ? A 3 ~ A I. FAR W5 ACa ~ -« : A s y nc ?.9qufl 5 t ; HAtfO LZ hAsync7asfc3andJ.e> ; 

. r.z ? A5CAL TAR *S AAs y r.cSe I ect ( SOCKZT s, HWNO hWnd. r.z v«s<;, 

Lorq I£ver. t ) ; 

#:Mef cpLusplus 

j 

/■ M:c:osof: windows Extended ddta. types •> 

* ypedef scf:cc socfcadcr SGCKAOCR; 
cypedaf scruc: sock Add r "PSOCXAOOR; 
typed*; struct socfcador TAR * LPSOCKAODR; 

rypedef jc:uc: soc>.iddr_in SOCKA0DR_CN; 
typede f s:ruc: socitaddr~in • ?SOCiCA0OR_:M; 
cypecef struct socJeaddr_m FAR ' L?SOCXAQDR_I N; 

typede f struct li.-.ger L £ MGER ; 
typecef struct linear •? LINGER ; 
typedef struct Linear FAR LINGER ; 

typede f struct m_addc EN_AD0R; 
typede f struct in'acdr *?Tn_A00R; 
typede f struct m~iddr FAR • L? IN_AD0R ; 

typ*def struct fd_set rC_5ET; 
typed* f struct fd_set •?F0_5ET; 
typede C struct fd_set TAR -L?FD_S£T; 

typede; struct fcoscent HOSTENT; 
typedef struct hosta.-.t • PHOSTENT ; 
typed«f struct hostar.t FAR • LPHOSTENT ; 

typ«def struct aarv«r.: StRVENT; 
typede; struct servant "PSZRVENT; 
typede ! struct servant FAfl 'LPSERVENT; 

typede! struct p cot cent PROTOENT; 
typede; struct protoer.t •PPROTOEt^TT; 
typede ; struct protoer.t FAR 'LPPROTOENT; 

cypede; struct ttmev*l T I ME VAX. ; 
typedeC struct timeval ♦PTEMZVAI.; 
typedef struct timeval FAJl *LPT:K£VAL; 

/ • 

* Wmdowj .Tt«j3d^4 parameter composition and c« compos it ion 

* na: ros . 

* WSAMAXEASYNCREPIV is intended .'or us* by the Windows Sockets i.Tipl ement at 1 on 

* when const ruct i.-.c the respons* to a ws AAs yncCetX3y r ( ) routine. 
•/ 

• define WSAMAKEAS YNCR£? LY < bu J L en, a r ro C) MAXSL.CNG Ou.' L en, error) 

/ • 

* WSAttAX£aELZC7R£PLr is intended for use by the Wi-aows Sockets i:npiament at ion 

* whan constructing tno respor.se to wsAAsyncSe t act < > . 
•/ 

>defi.-.e WSAMAKESELZCTRZPIY (evant, error) MAKE LONG (event , error) 

/ • 

* WSACETAS'fNCSUF'utN ts l -tended for usa by the Windows Sockets application 

* to extract the buffer langth from the LParajn m the response 



:r.t O'ifLer.); 
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* -o a WSACe-.X3y Y ( ) . 

tzai : re W3ACITA3 YS*C3Cj"-.IN t :? a ra.-n) *_ : wc R 3 ( L ? 4 r a.r ) 

* W3 AG ETA 3 YNCE33C3 is ir.* ended for -se ay -he Windows 3oc>.e*s application 

* -o g x t : i^* me error ;ode from che LParam i r. zr.e response 

* to * W5ACecX3y Y ( ) . 
•/ 

»ief:na WS ACETA3 YNCEP.RCR { 1 ? a ram ) H I WORD { I ? a r am ) 

* WSAGETSELECTEVENT is ::.:«nded for use by -he Windows Soc«:3 appUcac;or. 
" - o ax: race ^ha evenc code from che LParam i.n che respor.se 

* co a WSAAayncioLec: ( ) . 
•/ 

»ae!:na WS AGETS ELECTEVENT ( L ?aram> LOWCRO (IPdram) 

/ • 

* WSAGE73ELECTERROR is intended for use by the Windows Sockets application 

* co exc race che error code t rom che LParam in che response 

* co a WSAAayncSelect ( ) . 
•/ 

♦ define WSAGETSELECTERRCR ( LParan) H IWORO ( L?a ram ) 

lendi f / • WiNSOCKAPT •/ 



137 



EP 0 770 958 A1 
Appendix B: Notes for Windows Sockets Suppliers 125 



Appendix B. Notes for Windows Sockets Suppliers 
B.1 Introduction 

A Windows Sockets implementation must Implement ALL the runctiouaiiry described in the Windows 
Sockets documeautioQ. Validation of compliance is discussed In section B.8. 

| Windows Sockets Version 1. i implementations must support both TCP and UDP type sockets. An 
implementation may support raw sockets (of type SOCK_RAW). but their use is deprecated. 

Certain APIs documented above have special notes for Windows Sockets implementors. A Windows 
Sockets implementation should pay special attention to conforming to the API as documented. The 
Special Notes are provided for assistance and clarification. 



B.2 Windows Sockets Components 
B.2.1 Development Components 

The Windows Sockets development components for use by Windows Sockets application developers will 
be provided by each Windows Sockets supplier. These Windows Sockets development components are: 

ComPQClCCU Description 

Windows Sockets Documentation This document 

WINSOOCLIB file Windows Sockets API Import Library 

WTNSOCK.H file Windows Sockets Header File 

NETDB.H file Berkeley Compatible Header Fde 

ARPA/INET.H file Berkeley Compatible Header FUe 

SYS/TIME.H file Berkeley Compatible Header Hie 

SYS/SOCKET.H file Berkeley Compatible Header Fde 

NETTNET/IN.H file Berkeley Compatible Header Fde 



B.2. 2 Run Time Components 

The run time component provided by each Windows Sockets supplier is: 
Component, Description 

WINSOCKJDLL The Windows Sockets API implementation DLL 



B.3 Multlthreadednesa and blocking routines. 

Data areas returned by. for example, the getXby Y0 routines MUST be on a per thread basis. 

Note that an application MUST be prevented from making multiple nested Windows Sockets function 
calls. Only one outstanding function call will be allowed for a particular Any Windows Sockets 
call performed when an existing blocking call is already outstanding will fail with an error code of 
WSAETNFR OGRESS. There are two exceptions to this restriction: WSACancelBlockingCailO and 
WSAisB locking 0 may be called at any rime. Windows Sockets suppliers should note that although 
preliminary drafts of this specification indicated that the restriction only applied to blocking function 
calls, and that it would be permissible to make uon-btccking calls while a blocking call was in progress, 
mis is no longer true. 

Regarding the implementation of blocking routines, the solution in Windows Sockets is to simulate the 
blocking mechanism by having each routine call PeekMessageO as it waits for the completion of its 
operation. In anticipation of this, the function WSASetBlcckingHookO is provided to allow the 
programmer to define a special routine to be called instead of the default PeekMessageO loop. The 
blocking hook functions are dismissed in more detail in 4.3. 13. WSASetfilockingHookQ. 
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B.4 Database Fifes 

The database routines La the geLXby Y() family (getbostbyaddrO. etc ) were originally designed (in the 
first Berkeley UNIX releases) as mechanisms for looking up information. La text databases. A Windows 
Sockets supplier may choose co employ local files OR a name service to provide some or all of this 
Loformatioa. If local files exist, the format of the files must be identical to chat used in BSD UNIX, 
allowing for the differences in text file formats. 

B.5 FDJSSET 

It is necessary to implement the FD_ISSET Berkeley macro using a supporting function: 

WSAFDlsSetQ. It Is the responsibility of a Windows Sockets implementation to make this available 

as pan of the Windows Sockets API. Unlike the other functions exported by a Windows Sockets DLL. 
however, this function is not intended to be invoked directly by Windows Sockets applications: it should 
be used only to support the FD.ISSET macro. The source code for this function is listed below: 

mc FAR 

wSAFDIaSet (SOCKET fd, fd_set FAR *aet) 

( 

int i - set->£d_counc; 

while (i — ) 

if (sec->fd_array (i ] — fd) 
return 1; 

return 0; 



B.6 Error Codes 

In order to avoid conflict becween various compiler environments Windows Sockets implementations 
MUST re rum the error codes listed in the API specification, using the manifest constants beginning with 
"WSA". The Berkeley-compatible error code definitions are provided solely for compatibility purposes 
for applications which are being ported from other plarforms. 

B.7 DLL Ordinal Numbers 

The wiosock.def file for use by every Windows Sockets implementation is as follows. Ordinal values 
starting at 1000 are reserved for Windows Sockets implementors to use for exporting private interfaces to 
their DLLs. A Windows Sockets implementation must not use any ordinals 999 and below except for 
those APIs listed below. An application which wishes to work with any Windows Sockets DLL must use 
only those routines listed below; using a private export makes an application dependent on a particular 
Windows Sockets implementation. 

wt nsocK . def 
System: MS-Windows J.x 
Siitaary: Modulo definition file for Windows Sockets OLL- 

LI3RAAr wtNSOCK ; Application's module name 

0Z SCRIPT [CM *3S0 Socicet A?: for Windows' 

iXETYPE WINDOWS ; required for all windows applications 

ST'JS ' W£ NS7*Ji . ZXt * ; generates error messace if application 

; is run wicnout Windows 

; CCOE can be F ! X I 0 in memory because of potential upcalls 
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; 0 A T A .t,us: -« 5 I NCL£ i* 2 it 4 ~ ~.'S.Z0 1 JCi*. $i*c« -. .1 l s . s 4 : 1.1 

-ata ??.£ica: r : x i 3 3:>;c;.2 



HIA?3 :z£ 
STACKS " ZZ 



All J'^r.ct'.or.s tr.a* 
.t> u s - o« <a x pc r " . 
-.ere musi hava o::: 

iX PORTS 



1 called oy sny Hi, niows ro : r. e 
JG'-:::or.il «:<po::s oayona "Mosa : : 
-::moers '.00 2 or oo*/«. 



;»of 



accapc 


•it 




3 2 






conned 


34 




35 


gel soc jcname 


36 


qe:aoc'.<opc 


37 


hconl 


39 


h.cons 


39 


x r.a' __addr 


310 


ir.ac_r.coa 


3U 


locc I sock at 


312 


Uscer. 


31 j 


n:oh 1 


5 L 4 




315 


racv 


316 


recvf corn 


417 


select 


313 


sand 


313 




4 ?n 
» * J 


secsocXopc 


e2i 


shutdown 


322 


socKsc 


323 


gachoscby addr 


■3 5 L 


<3« C ho s c b y n d*t»« 


352 


gacpcotobynama 


353 


gacpcacobynunbar 


354 


g«C3«rvby n-djr.a 


835 


<7«ta«rvbypoct 


356 


gatnoscn&ma 


957 


WSAAsyncSalact 


810 L 


WSAAsyncCatHoscByAddr 


e L02 


wsAAsyncGacHosc 3yNa/n* 




WSAAayncGacP rotoByNuxnbar 


3L04 


WSAAsyncCacProeoByNama 


8 LOS 


WSAAsyncCaCSarvByPort 


3105 


W5AA3yncC«cS#rv9ySano 


9 107 


WSACancaLAsyncRequasc 


3103 


WSASat BlocfcingHook. 


3L09 


WSAUnhookBlockingHoo* 


3110 


wsAGac Last Error 


3111 


wSASacLaat Error 


31L2 


WSACanca*BLoc*j.ngCall 


3U3 


WSAEsBlocJcinq 


31 L4 


WSAStactup 


3115 


WSACloanup 


31 L 5 


WSAFOraSac 


312 1 


wi? 


3 500 



RES t -ENTNAKE 



B.8 Validation Suite 



Hie Windows Sockets API Tester (WSAT) to ensure Windows Sockets compatibility between Windows 
Sockets DLL implementations is currently in beu test This beta version includes functionality testing of 
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the Windows Sockets interface and is supported by a comprehensive scripting language. The final version 
of WSAT will be available in Spring 1993. If you wish to receive the tester or more inform an on on the 
beta, send email to wsat@aiicrosoft.com. 
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Appendix C. For Further Reference 

"This specific a a od is intended to cover the Windows Sockets interface to TCP/IP in detail. Many details 
of TCP/IP and Windows, however, are intentionally omitted in the interest of brevity, and this 
specificarioa often assumes background knowledge of these topics. For more information, the foUowing 
references may be helpful: 

Braden. R.[1989]. RFC 1122, Requirements for Internet Hosts-Communication Layers. Internet 
Engineering Task Force. 

Comer. D. [1991]. Inte rnetworking with TCP/IP Volume I: Principles, Protocols, and Architecture. 
Prentice Hall. Englewood Cliffs. New Jersey. 

Comer. D. and Stevens. D. [1991]. Internetworking with TCPI1P Volume 11: Design, Implementation, and 
Internals. Prentice Hall. Englewood Cliffs. New Jersey. 

Comer. D. and Stevens. D. [1991]. Internetworking with TCPUP Volume 111: Client-Server Programming 
and Applications, Prentice Hall. Englewood Cliffs. New Jersey. 

Leffler, S. et ai. An Advanced 4.3BSD Interprocess Communication Tutorial. 
Petzold. C. [1992], Programming Windows 3.1. Microsoft Press. Redmond. Washington- 
Stevens. WJl. [1990]. Unix Network Programming. Prentice Hall. Englewood Cliffs. New Jersey. 
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Appendix D. Background Information 
D.1 Legal Status ot Windows Sockets 

The copyright for Lhc Windows Sockets specification is owned by the specification authors listed oq the 
tide page. Permission is granted to redistribute this specification in any form, provided that the contents 
of the specificadon are aoi modified. Windows Sockets unplemeutors are encouraged to include rhi< 
specification with their product documentation. 

The Windows Sockets logo on the ride page of this document is meant for use on both Windows Sockets 
implementations and for applications that use the Windows Sockets interface. Use of the logo is 
encouraged on packaging, documentation, collateral, and advertising. The logo is 

available oq microdyne.com in pub/winsock as winsocicbmp. The suggested color for the logo's tide bar 
is blue, the electrical socket grey, and the text and outline black. 



0.2 The Story Behind the Windows Sockets Icon 

(by Ali stair Banks. Microsoft Corporation) 

We thought we'd do a "Wind Sock" at one stage-but you try to get that into 32x32 bits! It would have had 
to look wavy and colorful, and... well, it just didn't work. Also, our graphics designers have "opinions" 
about the icons truly representing what they are-people would have thought this was "The colorful wavy 
tube specification 1.0!" 

I cried to explain "API" 'Programming Interface" to the artist— we ended up with toolbox icons with lie tie 
flying windows 

Then we came to realise that we should be going after the shortened form of the name, rather the nam* in 
full... Windows Sockets... And so we went for that - so she drew (now remember Tm Fnglicb and you're 
probably American) "Windows Spanner". aJca. a socket wrench. In the U.S. you'd have been ffllWng 
about the "Windows Socket spec" OK. but in Fngland that would have been translated as "Windows 
Spanner Spec 1.0" * so we went to Electrical sockets - well the first ones came out looking like "Windows 
Pignose Spec 1.0"!!!! 

So how do you use 32x32. get on international electrical socket! You take the square type (American & 
English OK. Europe & Australia are too rounded}— you choose the American one. because it's on the wall 
in front of you (and it's more compact (but less safe. EMHO) and then you turn it upside down, thereby 
compromising its nationality! 

| (TMHO = "In My Humble Opinion"-ed.] 
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XtAppAddlnput \_ 



■ Xt - Event Handling — 



Name 

XtAppAddlnput — register a new file as an input source for a given application. 
Synopsis 

Xclr.pucld XcAppAdd Cnpuc ( apa^conzexc, source, condition, proa, ci ienz_dazd) 
X:ApoCor.cex: <jpp_conc exc ; 
Lnc source; 
XcPoincer condi c ion; 
XcrnpucCalibackProc pcoc; 
XcPoincer ci ienc^dac* ; 

Arguments 

*pp_concexc Specifies the application context that identifies the application. 

source Specifies the source 6le descriptor (on a PO SEX -based system) or other 

opera ung-sy stem-dependent device specification. 

condition Specifies a mask that indicates a read, write, or exception condiuon or some 
operating- system-dependent condition. 

pcoc Specifics the procedure that is to be caJIed when condition is true. See 

XtInputCallbackProc(2). 

cllcnc^daca Specifies for argument source to be passed to proc when I/O is available. 
Description 

While most applications are driven only by X events, some applications need to incorporate 
other sources of input. XtAppAddlnput allows an application to integrate notification of 
pending file data into the event mechanism. The application uses XtAppAddlnput to regis- 
ter a file with the Intrinsics read routine. When I/O is pending on the file source, the regis- 
tered callback procedure pcoc is invoked, source is usually file input but can also be file 
output. (Note that "file" means any sink or source of data.) 

XtAppAddlnput also specifies the condition under which source can generate events. 
The legal values for condition are operating- system-dependent On a POS DC -based system, 
the possible values are XtlnputReadMask, XtlnputWriteMaaJc, or Xt InputExcept - 
Mask. The masks cannot be ORed together. These limit the invocation of proc to either a 
pending read, write, or exception condiuon on the source file. Sec the POSEX system select 
call for discussion of these conditions. 

Callback procedures that are used when there are file events are of type XtlnpucCallbaclc- 
Proc. 

Note that when reading from a socket, you should be careful not to close the end of -the socket 
that is waiting before exiting the XtAppMainLoop. If you do this, you will get an infinite 
loop, in which the proc is called repeatedly, while the Intrinsics wait for an EOF to be read. 

Sec Chapter 8, More Input Techniques, in Volume Four, X Toolkit fncrinsics Programming 
Manual, for a complete example using this function. 



56 X Too Our Intrinsics Reference Manual 
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Xt - Event Handling (continued) XtApp AddlnpU t 

See Also 

XtRtmavclnp ul ( I ), 
Xi!npusC<2l(bcu:kProc(2). 
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SO 



J XtRemovelnput 

^%\- Evant Handling- 

XtKemoveLnput — unregiscer a file procedure, a pipe procedure, or a socket procedure. 

Synopsis 

void XcSerrove Inpuc ( i d) 
Xtir.autid id; 

Arguments 

id Specifies the ID returned from the corresponding xtAppAdd Input call. 

Description 

XtRemovelnput causes the Intrinsics to stop watching for events from an alternate input 
source registered with Xt AppAddlnput. Alternate input events are usually operating system 
reads, but they can be any I/O operation supported by the operating system. 
For more general discussion of alternate input events, sec Chapter 8. More Inpui Techniques. 
in Volume Four. X Toolkit (nrrinsics Programming Manual. 

S*6 Also 

XtAddJnpui{\) % XlAppAddInpux{\). 




X Tooikit Intrinsics Refmnc* Manual 30 f 
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XtAppAddTimeOut V _ X t - Ev.nt Handling - 

XtAppAddTimeOut — invoke a procedure after a specified timeout. 
Synopsis , 

Xcrncerrvalld XtAppAddTimeOut ( app_concexc, interval, proc, clienc_daza) 
XcAopCancex- dpp_con:exc; 
unsigned Long incsrval; 
XtTimecCaL LbacicP roc pcoa; 
XcPoincer ciisnc^daca; 

Arguments 

d pp cancsxc Specifies the application context for which the timer is to be sec 
incecval Specifies the time interval in milliseconds. 

pcoc Specifics the procedure that is to be called when the time expires. See Xt- 

Time rCallbac kP roc(2). 
cllenc_daza Specifies the argument to be passed to the specified procedure when it is 

called. 

Description . 

XtAppAddTimeOut allows a program to have a function called after a specified timeout. 
XtAppAddTimeOut creates ihe timeout and returns an identifier for it The length of the 
timeout value is interval milliseconds. 

The Intrinsics invoke the specified callback when incerval elapses, and the timeout is 
removed from the event queue. 

The return value XtlntervallD uniquely identifies the pending timer pseudo-event. The 
pending event can be deleted from the queue before the interval expires by calling Xt- 
RemoveTimeOut. 

The callback procedure pointer that is invoked when timeouts expire is of type XtTimer- 
CallbackProc. 

XtAppNext Event and XtAppPeekEvent dispatch timer queue entries. 
See Also 

XtAppNextEvcnt(\\ XtAppPeck£vcni(\). XtDispatch£veni(l). XtRemasxTimtOuiil). 
X{fvru:rCallbackProc{2). 
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XtRemoveTimeOut V X t - event Handling^ 

Name 

XtRemoveTimeOut — unregister a timeout procedure. 
Synopsis 

void X- Remove? LxeCuC ( id) 
X::r.;e:vaitd - - 

Arguments 

id Specifies the (D for the limeout registration to be destroyed. 

Description 

XtRemoveTimeOut removes the timeout specified by id. id is the value returned by cither 
XtAppAddTimeOuc or XtAddTimeOut. 

Note that timeouts are automatically removed once they expire and the callback has been 
called. 

For an example and discussion of timeouts, sec Chapter 8. Mors Input Techniques, in Volume 
Four. X Toolkit Inrrinsics Programming Manual. 

See Also 

XtAddT'uneOui(\)* XtAppAdJTmOui{\). 
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Claims 

1. A computer system comprising: 

s A. at least one applications program for performing predetermined processing operations, the applications 

program issuing WinSock socket calls: 

B. a Unix operating system API for providing, in response to Unix socket calls, Unix socket services in con- 
nection with at least one socket connection to another computer system over a network; and 

10 

C. a WinSock socket driver for receiving WinSock socket calls from said applications program and emulating 
said WinSock socket calls in connection with Unix socket calls to said Unix operating system API. 

2. A computer system as defined in claim 1 in which said Unix operating system API provides Unix socket services 
is in a blockable pre-emptive multi-tasking manner. 

3. A computer system as defined in claim 1 in which said WinSock socket driver emulates at least one WinSock 
socket call in a non-blockable non-pre-emptive multi-tasking manner. 

20 4. a computer system as defined in claim 3 in which said WinSock socket driver emulates said at least one WinSock 
socket call in connection with a blockable Unix socket call the blockable Unix socket call having a duration pa- 
rameter specifying a duration over which a specified operation to be performed, the blockable Unix socket call 
blocking other operations for the duration, the WinSock socket driver including: 

25 A. a timer for enabling generation of a timing indication at the end of a timing interval corresponding to the 

duration specified by the duration parameter: 

B. a blockable call issuer for issuing the blockable Unix socket call with a duration parameter specifying an 
instantaneous duration thereby enabling the specified operation to be performed instantaneously; and 

. 30 

C. a non-blockable iteration control element for, in a series of iterations, enabling the blockable call issuer to 
issue the blockable call until the timer generates the timing indication, the non-blockable control element being 
non-pre-emptively interruptible during each iteration while the blockable call is not being executed thereby to 
facilitate emulation of the WinSock socket call in a non-blockable manner. 

35 

5. A computer system as defined in claim 4, the WinSock socket driver operating in connection with a pre-emptive 
multi-tasking operating system program which provides a timer call, the timer enabling generation of the timing 
indication by using the timer call with a timer call duration corresponding to the duration specified by the duration 
parameter. 

40 

6. A computer system as defined in claim 5 in which the pre-emptive multi-tasking operating system program is the 
Unix operating system program with XWindows extensions. 

7. A computer system as defined in claim 6 in which the timer call comprises the XWindows XtAppAddTimeOut() call. 

8. A computer system as defined in claim 4 : in which the computer system establishes socket network connections 
with at least one other computer over a network, the applications program using the non-blockable call to obtain 
information as to the status ofa said network socket connection. 

so 9. a computer system as defined in claim 8 in which blockable call provides information as to a said network socket 
connection. 

10. A computer system as defined in claim 4 in which the WinSock socket call is a WinSock Synchronous Select call, 
and the blockable Unix socket call is a Unix Synchronous Select call. 

55 

1 1 . A computer system as defined in claim 3 in which said WinSock socket driver emulates said at least one WinSock 
socket call in connection with a non-blockable Unix/XWindows extension call for determining the occurrence ofa 
predetermined event, as determined by the WinSock socket call, in said computer system, the WinSock socket 
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driver including: 

A. a call issuer for issuing the non-blockable Unix/XWindows extension call and providing a call acknowledg- 
ment to the applications program; and 

5 

B. a response receiver for later receiving a response from the Unix/XWindows extension call and providing 
the response to the applications program 

thereby to provide that the computer system executes the WinSock socket call in a non-blocking manner. 

w 

12. A computer system as defined in claim 11 in which said non-blockable Unix/XWindows extension call comprises 
an XtAppAddlnputQ call. 

1 3. A method of operating a computer system, comprising the steps of: 

15 

A. enabling at least one applications program to performs predetermined processing operations, the applica- 
tions program issuing WinSock socket calls: 

B. emulating the WinSock socket calls to generate Unix socket calls: and 

20 

C. enabling a Unix operating system API to provide., in response to Unix socket calls, Unix socket services in 
connection with at least one socket connection to another computer system over a network. 

14. A method as defined in claim 1 3 in which said Unix socket calls operate in a blockable pre-emptive multi-tasking 
25 manner. 

15. A method as defined in claim 13 in which at least one said WinSock socket call is emulated in a non-blockable 
non-pre-emptive multi-tasking manner. 

30 16. A method as defined in claim 15 in which said at least one WinSock socket call is emulated in connection with a 
blockable Unix socket call, the blockable Unix socket call having a duration parameter specifying a duration over 
which a specified operation to be performed, the blockable Unix socket call blocking other operations for the du- 
ration, the WinSock socket call being emulated in accordance with the steps of: 

35 A. enabling generation ofa timing indication at the end of a timing interval corresponding to the duration spec- 

ified by the duration parameter: 

B. issuing the blockable Unix socket call with a duration parameter specifying an instantaneous duration there- 
by enabling the specified operation to be performed instantaneously; and 

C. in a series of iterations, enabling the blockable call issuer to issue the blockable call until the timer generates 
the timing indication, the non-blockable control element being non-pre-emptively interruptible during each 
iteration while the blockable call is not being executed thereby to facilitate emulation of the WinSock socket 
call in a non-blockable manner. 

17. A method as defined in claim 16, in which the emulation step is performed in connection with a pre-emptive multi- 
tasking operating system program which provides a timer call, the generation of the timing indication being enabled 
by using the timer call with a timer call duration corresponding to the duration specified by the duration parameter. 

so 18. A method as defined in claim 17 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program with XWindows extensions. 

19. A method as defined in claim 18 in which the timer call comprises the XWindows XtAppAddTimedutQ call. 

ss 20. A method as defined in claim 16, in which the computer system establishes socket network connections with at 
least one other computer over a network, the non-blockable call being used to obtain information as to the status 
of a said network socket connection. 
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21 . A method as defined in claim 20 in which blockable call provides information as to a said network socket connection. 

22. A method as defined in claim 16 in which the WinSock socket call is a WinSock Synchronous Select call, and the 
blockable Unix socket call is a Unix Synchronous Select call. 

5 23 A method as defined in claim 15 in which said at least one WinSock socket call is emulated in connection with a 
non-blockable Unix/XWindows extension call for determining the occurrence of a predetermined event, as deter- 
mined by the WinSock socket call, in said computer system, the WinSock socket driver .ncluding: 

,o A . issuing the non-blockable Unix/XWindows extension call and providing a call acknowledgment to the ap- 

plications program: and 

B. later receiving a response from the Unix/XWindows extension call and providing the response to the appli- 
cations program: 

thereby to provide that the computer system executes the WinSock socket call in a non-blocking manner. 

24. A method as defined in claim 23 in which said non-blockable Unix/XWindows extension call comprises an XtAp- 
pAddlnput() call. 

25 A WinSock socket driver for use in connection with a Unix operating system API, the WinSock socket driver re- 
ceiving WinSock socket calls from an applications program and emulating them using calls to the Unix operating 
system API, the WinSock socket driver including: 

25 A. a WinSock call verification element for, in response to receipt of a WinSock call from said applications 

program, verifying the emulatability of the received WinSock call, 

B an emulation element for issuing predetermined Unix operating system API calls as determined by the 
received WinSock call, and receiving responses generated in response to said Unix operating system API calls: 

30 . . 

C. a response generation element for generating a response to said WinSock socket driver call for prov.sion 
to said applications program. 

26. A WinSock socket driver as defined in claim 25 in which said WinSock call verification element, in verifying the 
35 emulatabililty of the received WinSock call, verifies any parameters provided in the call. 

27 A WinSock socket driver as defined in claim 25 in which said WinSock socket driver emulates said at least one 
WinSock socket call in connection with a blockable Unix socket call, the blockable Unix socket call having a duration 
parameter specifying a duration over which a specified operation to be performed, the blockable Unix socket call 

40 blocking other operations for the duration, the WinSock socket driver including: 

A. a timer for enabling generation of a timing indication at the end of a timing interval corresponding to the 
duration specified by the duration parameter; 

45 B a blockable call issuer for issuing the blockable Unix socket call with a duration parameter specifying an 

instantaneous duration thereby enabling the specified operation to be performed instantaneously: and 

C a non-blockable iteration control element for, in a series of iterations, enabling the blockable call issuer to 
issue the blockable call until the timer generates the timing indication, the non-blockable control element being 
so non-pre-emptively interruptible during each iteration while the blockable call is not being executed thereby to 

facilitate emulation of the WinSock socket call in a non-blockable manner. 

28 A WinSock socket driver as defined in claim 27, the WinSock socket driver operating in connection with a pre- 
emptive multi-tasking operating system program which provides a timer call, the timer enabling generation of the 

55 timing indication by using the timer call with a timer call duration corresponding to the duration specified by the 

duration parameter. 

29. A WinSock socket driver as defined in claim 28 in which the pre-emptive multi-tasking operating system program 
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is the Unix operating system program with XWindows extensions. 

30. A WinSock socket driver as defined in claim 29 in which the timer call comprises the XWindows XtAppAddTimeOut 
() call. 

5 

31. A WinSock socket driver as defined in claim 27 : in which the computer system establishes socket network con- 
nections with at least one other computer over a network, the applications program using the non-blockable call 
to obtain information as to the status of a said network socket connection. 

io 32. A WinSock socket driver as defined in claim 31 in which blockable call provides information as to a said network 
socket connection. 

33. A WinSock socket driver as defined in claim 27 in which the WinSock socket call is a WinSock Synchronous Select 
calL and the blockable Unix socket call is a Unix Synchronous Select call. 

75 

34. A WinSock socket driver as defined in claim 26 in which said WinSock socket driver emulates said at least one 
WinSock socket call in connection with a non-blockable Unix/XWindows extension call for determining the occur- 
rence of a predetermined event, as determined by the WinSock socket call, in said computer system, the WinSock 
socket driver including: 

20 

A. a call issuer for issuing the non-blockable Unix/XWindows extension call and providing a call acknowledg- 
ment to the applications program; and 

B. a response receiver for later receiving a response from the Unix/XWindows extension call and providing 
25 the response to the applications program 

thereby to provide that the computer system executes the WinSock socket call in a non-blocking manner. 

35. A WinSock socket driver as defined in claim 34in which said non-blockable Unix/XWindows extension call com- 
30 prises an XtAppAddlnput() call. 

36. A method for emulating WinSock socket calls from an applications program in connection with a Unix operating 
system API, the method including the steps of: 

35 A. verifying, in response to receipt of a WinSock call from said applications program, the emulatability of the 

received WinSock call, 

B. issuing predetermined Unix operating system API calls as determined by the received WinSock call, and 
receiving responses generated in response to said Unix operating system API calls; 

40 

C. generating a response to said WinSock socket driver call for provision to said applications program. 

37. A method as defined in claim 36 in which, during the verification step, any parameters provided in the call are 
verified. 

45 

38. A method as defined in claim 36 in which at least one said WinSock socket call is emulated in a non-blockable 
non-pre-emptive multi-tasking manner. 

39. A method as defined in claim 38 in which said at least one WinSock socket call is emulated in connection with a 
so blockable Unix socket call, the blockable Unix socket call having a duration parameter specifying a duration over 

which a specified operation to be performed, the blockable Unix socket call blocking other operations for the du- 
ration, the WinSock socket call being emulated in accordance with the steps of: 

A. enabling generation ofa timing indication at the end of a timing interval corresponding to the duration spec- 
ks ified by the duration parameter; 

B. issuing the blockable Unix socket call with a duration parameter specifying an instantaneous duration there- 
by enabling the specified operation to be performed instantaneously; and 
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C. in a series of iterations, enabling the blockable call issuer to issue the blockable call until the timer generates 
the timing indication, the non-blockable control element being non-pre-emptively interruptible during each 
iteration while the blockable call is not being executed thereby to facilitate emulation of the WinSock socket 
call in a non-blockable manner. 

40. A method as defined in claim 39 in which the emulation step is performed in connection with a pre-emptive multi- 
tasking operating system program which provides a timer call, the generation of the timing indication being enabled 
by using the timer call with a timer call duration corresponding to the duration specified by the duration parameter. 

41. A method as defined in claim 40 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program with XWindows extensions. 

42. A method as defined in claim 41 in which the timer call comprises the XWindows XtAppAddTimeOut() call. 

43. A method as defined in claim 39, in which the computer system establishes socket network connections with at 
least one other computer over a network, the non-blockable call being used to obtain information as to the status 
ofa said network socket connection. 

44. A method as defined in claim 43 in which blockable call provides information as to a said network socket connection. 

45. A method as defined in claim 39 in which the WinSock socket call is a WinSock Synchronous Select call, and the 
blockable Unix socket call is a Unix Synchronous Select call. 

46. A method as defined in claim 38 in which said at least one WinSock socket call is emulated in connection with a 
non-blockable Unix/XWindows extension call for determining the occurrence of a predetermined event, as deter- 
mined by the WinSock socket call, in said computer system, the WinSock socket driver. including: 

A. issuing the non-blockable Unix/XWindows extension call and providing a call acknowledgment to the ap- 
plications program: and 

B. later receiving a response from the Unix/XWindows extension call and providing the response to the appli- 
cations program; 

thereby to provide that the computer system executes the WinSock socket call in a non-blocking manner. 

47. A method as defined in claim 46 in which said non-blockable Unix/XWindows extension call comprises an XtAp- 
pAddlnputO call. 

48. For use in connection with a computer, a non-pre-emptive multi-tasking emulator for emulating a blockable call 
issued by an applications program, the blockable call having a duration parameter specifying a duration over which 
a specified operation to be performed, the blockable call blocking other operations for the duration, the emulator 
emulating the blockable call in a non-blocking manner, the emulator comprising: 

A. a timer for enabling generation of a timing indication at the end of a timing interval corresponding to the 
duration specified by the duration parameter: 

B. a blockable call issuer for issuing the blockable call with a duration parameter specifying an instantaneous 
duration thereby enabling the specified operation to be performed instantaneously; and 

C. a non-blockable iteration control element for, in a series of iterations, enabling the blockable call issuer to 
issue the blockable call until the timer generates the timing indication, the non-blockable control element being 
non-pre-emptively interruptible during each iteration while the blockable call is not being executed. 

49. An emulator as defined claim 48 in which the blockable call operates in a polling mode in which it performs the 
operation instantaneously and a non-polling mode in which it performs the operation over a selected period of 
time, the mode being indicated by the duration parameter, the blockable call issuer issuing the blockable call using 
the duration parameter which indicates the polling mode. 

50. An emulator as defined in claim 48 in which the blockable call is executed by a pre-emptive multi-tasking operating 
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system program. 

51 . An emulator as defined in claim 50 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program. 

5 

52. An emulator as defined in claim 48, the emulator operating in connection with a pre-emptive multi-tasking operating 
system program which provides a timer call, the timer enabling generation of the timing indication by using the 
timer call with a timer call duration corresponding to the duration specified by the duration parameter. 

io 53. An emulator as defined in claim 52 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program with XWindows extensions. 

54. An emulator as defined in claim 48 in which the computer establishes socket network connections with at least 
one other computer over a network, the applications program using the non-blockable call to obtain information 

is as to the status of a said network socket connection. 

55. An emulator as defined in claim 54 in which blockable call provides information as to a said network socket con- 
nection. 

20 56. A method of controlling a computer to emulate, in a non-pre-emptive multi-tasking manner a blockable call, the 
blockable call having a duration parameter specifying a duration over which a specified operation to be performed, 
the blockable call blocking other operations for the duration, the blockable call being emulated in a non-blocking 
manner, the method comprising the steps of: 

25 A. enabling generation of a timing indication at the end of a timing interval corresponding to the duration 

specified by the duration parameter: 

B. issuing the blockable call with a duration parameter specifying an instantaneous duration thereby enabling 
the specified operation to be performed instantaneously: and 

30 

C. in a series of iterations, enabling the issuance of the blockable call until the timing indication is generated, 
the operations being non-pre-emptively interruptibie during each iteration while the blockable call is not being 
executed. 

35 57. A method as defined claim 56 in which the blockable call operates in a polling mode in which it performs the 
operation instantaneously and a non-polling mode in which it performs the operation over a selected period of 
time, the mode being indicated by the duration parameter, the blockable call being issued using the duration pa- 
rameter which indicates the polling mode. 

40 58. A method as defined in claim 56 in which the blockable call is executed by a pre-emptive multi-tasking operating 
system program. 

59. A method as defined in claim 58 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program. 

45 

60. A method as defined in claim 56, the method being performed in connection with a pre-emptive multi-tasking 
operating system program which provides a timer call the timing indication by use of the timer call with a timer 
call duration corresponding to the duration specified by the duration parameter. 

so 61. A method as defined in claim 60 in which the pre-emptive multi-tasking operating system program is the Unix 
operating system program with XWindows extensions. 

62. A method as defined in claim 56, in which the computer establishes socket network connections with at least one 
other computer over a network, the applications program using the non-blockable call to obtain information as to 

55 the status of a said network socket connection. 

63. A method as defined in claim 62 in which blockable call provides information as to a said network socket connection. 
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'lOO. RECEIVE A WINSOCK SYNCHRONOUS SELECT 
CALL FROM AN APPLICATIONS PROGRAM 21 AND 
OBTAIN THE CONTEXT OR TASK IDENTIFIER THEREOF 



i 



101. VERIFY THAT SOCKET STRUCTURE HAS BEEN 
INITIALIZED FOR THE TASK IDENTIFIED BY THE TASK 
IDENTIFIER BY WAY OF A SOCKET START CALL 



YES 



NO 



102. RETURN AN ERROR VALUE 



103. DETERMINE WHETHER THERE IS AN 
OUTSTANDING BLOCKING OPERATION ASSOCIATED 
WITH THE APPLICATIONS PROGRAM 21 WHICH HAS 



NO 



YES 

1 



104. RETURN AN ERROR VALUE 



J 
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'105. ACCESS SOCKET IDENTIFIER TABLE(S) WHICH ^ 
ARE IDENTIFIED BY THE -RD-SOCK-PTFT READ 
SOCKET POINTER. "WRT-SOCK-PTR" WRITE SOCKET 
POINTER AND "EXC-SOCK-PTR" EXCEPTION SOCKET 
POINTER PARAMETERS AND OBTAIN UNIX FILE 
DESCRIPTOR INFORMATION FOR SOCKET 

^DENTIFIERS LISTED THEREIN 



106. DETERMINE WHETHER ERROR ENCOUNTERED IN 
CONNECTION WITH SOCKET IDENTIFIERS OR 
GENERATION OF THE UNIX FILE DESCRIPTOR 
INFORMATION 



YES 

JL 



107. RETURN AN ERROR VALUE 



YES 



1 


f 


r 

108. DETERMINE WHETHER THE "TM-OUT" TIMEOUT 
DURATION PARAMETER SPECIFIED A NULL VALUE. 






f 


109. DETERMINE WHETHER THE TIMEOUT DURATION 
PARAMETER SPECIFIED A ZERO VALUE 





NO 

0 0 

FIG. 3A 
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0 




110 ISSUE AN XtAppAddTlmoOutO XWINDOWS CALL 
TO THE UNIX OPERATING SYSTEM PROGRAM AND 
SET A TIMER TASK 



111. ISSUE APPROPRIATE UNIX SOCKETS' UNIX 
SYNCHRONOUS SELECT CALL WITH TIMEOUT 
DURATION OF ZERO 



'1 12. AFTER RETURNING FROM THE UNIX 
SYNCHRONOUS SELECT CALL, TEST THE TM-OUT' 
TIMEOUT DURATION PARAMETER PROVIDED IN THE 
W1NSOCK SYNCHRONOUS SELECT CALL TO 
DETERMINE WHETHER IT WAS NON-ZERO 



NO 



YES 



113. DETERMINE WHETHER THE VALUE PROVIDED IN 
RESPONSE TO THE UNIX SYNCHRONOUS SELECT 
CALL PROVIDED A NON-ZERO RESPONSE 



NO 

A. 



114. CALL BLOCKING HOOK FUNCTION AND 
DETERMINE WHETHER (i) THE APPLICATIONS 
PROGRAM 21 HAS TERMINATED THE WINSOCK 
SYNCHRONOUS SELECT OPERATION OR (ii) THE 
TIMER TASK FLAG HAS BEEN CLEARED BY THE 
TIMING OUT OF THE XtAppAddTimeOut() CALL 



YES 



0 



YES 

6 



FIG. 3B 
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115. TERMINATE OPERATIONS AND RETURN TO THE 
CALLING APPLICATIONS PROGRAM 



116. ISSUE AN XtRemoveTlmeOut XWINDOWS CALL TO 
CANCEL THE XtAppAddTimeOut CALL 



i 



117. CLEAR THE TIMER TASK FLAG 



118. IDENTIFY THE PARTICULAR SOCKJET(S) 
DETERMINED TO BE READABLE, WRITABLE OR FOR 
WHICH AN EXCEPTION WAS DETECTED AND 
CONVERT THE SOCKET IDENTIFIERS FROM THE UNIX 
FILE DESCRIPTOR IDENTIFIERS TO SOCKET 
^IDENTIFIERS 



119. 
21 



RETURN TO CALLING APPLICATIONS PROGRAM 



FIG. 3C 
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YES 



130. RECEIVE AW ASYNCHRONOUS SELECT CAUL 
FROM AN APPLICATIONS PROGRAM 21 AND OBTAIN 
THE CONTEXT OR TASK IDENTIFIER THEREOF 



I 



^31. VERIFY THAT THE SOCKET STRUCTURE HAS 
BEEN INITIALIZED FOR THE TASK IDENTIFIED BY 
THE TASK IDENTIFIER BY WAY OF A SOCKET START 

. CALL — — 

NO 

+ 



132. RETURN AN ERROR VALUE 



YES 



133. DETERMINE WHETHER "SOCK-ID" SOCKET 
IDENTIFIER PARAMETER IS A VALID SOCKET 
IDENTIFIER AND IF THE APPUCATIONS PROGRAM 21 
HAS PERMISSION TO ACCESS THE SOCKET 
V 



NO 

_±_ 



134. RETURN AN ERROR VALUE 



j 



NO 



135. DETERMINE WHETHER THERE IS AN 
OUTSTANDING BLOCKING OPERATION ASSOCIATED 
WITH THE APPLICATIONS PROGRAM 21 WHICH HAS 
NOT BEEN COMPLETED 



YES 



136. RETURN AN ERROR VALUE 



J 



FIG. 4 
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0 



1 37. CLEAR A "BLOCKING" FLAG 



i 



138. DETERMINE WHETHER THE CAUL IS TO 
RE-ENABLE NOTIFICATION FOR A NETWORK EVENT 



YES 



139. ADD THE TYPE OF NETWORK EVENT FOR 
WHICH THE APPUCATIONS PROGRAM 21 IS TO BE 
NOTIFIED TO A UST OF NETWORK EVENTS TO BE 
MONITORED 



/f40. SUBSTITUTE THE NETWORK EVENT IDENTIFIED^ 
BY THE "EV-ID" EVENT IDENTIFIER PARAMETER FOR 
THE MONITORED NETWORK EVENT UST AND ISSUE 
Unix/XWindow* XtRemoveJnput() CALL(S) TO THE 
Unix/XWtndow* OPERATING SYSTEM PROGRAM TO 

V^NABLE IT TO STOP MONITORING OF NETWORK ^ 



NO ^ 



141. DETERMINE WHETHER THE NETWORK EVENT 
ASSOCIATED WITH THE ASYNCHRONOUS SELECT 
CALL IS A SOCKET-CLOSE EVENT OR AN 
OUT-OF-BAND DATA RECEIVED EVENT 



YES 



142. GENERATE AN XtAppAddlnputQ CAUL IN WHICH 
THE CONDITION IS SPECIFIED AS AN 
XtinputExc*ptMask "EXCEPTION" MASK 



FIG. 4A 



NO 
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<2 



NO 



143. DETERMINE WHETHER THE NETWORK EVENT 
ASSOCIATED WITH THE ASYNCHRONOUS SELECT 
CALL IS A SOCKET-ACCEPT EVENT OR A READ 
READINESS NOTIFICATION 



YES 



144. GENERATE AN XtAppAddInput() CALL IN WHICH 
THE CONDITION IS SPECIFIED AS AN 
XtJnputReadMask "READ" MASK 



145. DETERMINE WHETHER THE NETWORK EVENT 
ASSOCIATED WITH THE ASYNCHRONOUS SELECT 
CALL IS A COMPLETED-SOCKET-CONNECTiON 
NOTIFICATION OR A WRJTE-READINESS 
NOTIFICATION 



YES 



146. GENERATE AN XtAppAddlnput{) CALL IN WHICH 
THE CONDITION IS SPECIFIED AS AN 
XtJnputWnteMask "WRITE** MASK 



) 



147. PROVIDE A RETURN ACKNOWLEDGMENT 
VALUE TO THE APPLICATIONS PROGRAM 21 WHICH 
ISSUED THE ASYNCHRONOUS SELECT CALL 



FIG. 4B 
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150. RECEIVE RESPONSE TO XtAppAddlnputQ CALL 



] 



151. TEST A RE-ENTRANT CONTROL FLAG TO 
DETERMINE WHETHER IT IS CURRENTLY 



PROCESSING A RESPONSE 



] 



NO 

I 



152. CONDITION THE RE-ENTRANT CONTROL FLAG 
TO INDICATE THAT IT IS CURRENTLY PROCESSING A 
RESPONSE 



FLAG "| 
JSING A I 



153. DETERMINE THE TYPE OF RESPONSE 



I 



154. GENERATE A MESSAGE IDENTIFYING THE 
RESPONSE 

^ i 



155. POST MESSAGE IN A RESPONSE QUEUE 
ASSOCIATED WITH THE CALLING APPLICATIONS 
PROGRAM 21 



I 



156. CONDITION THE RE-ENTRANT CONTROL FLAG 
TO INDICATE THAT IT IS NOT CURRENTLY 
PROCESSING A RESPONSE 



FIG. 4C 
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